@vzn/vx-migrate 0.0.637 → 0.0.638

package/README.md

@@ -43,7 +43,7 @@ Until `bunx @vzn/vx-migrate` writes native config, `vx run build --all` maps eve
 ### What it does not do
 
 - A task the package's own `vx.config` already declares is left alone — the plugin fills, it never overwrites. Migrate a package by writing its config; the rest of the repo keeps running from `turbo.json`.
-- The mapping's gaps are the migration's gaps, reported as warnings on every run instead of `TODO(vx-migrate)` comments: `$TURBO_ROOT$` tasks, an env name vx cannot key that the run's environment sets (`FOO_?`, which Turbo reads literally), unknown turbo keys. A persistent task's readiness note (`readyWhen`) is reported only when something depends on it — with no dependent there is nothing to gate (refine printed it for 375 `dev` targets a run). `bunx @vzn/vx-migrate --dry` lists the same set once. Each gap is one line per run for every task that carries it, not one per task (n8n marks `dev` and `watch` persistent in most of its 84 packages; astro negates `vendor/**` in the outputs of 57 tasks). A per-package `{ "extends": false }` with nothing else is Turbo's opt-out and maps to no task; with keys, the task runs on those keys alone. A glob that climbs out of the package (`../../packages/app-store/*.generated.ts`) is re-anchored on the workspace root as a `workspaceFiles` glob. A negated output under a literal-rooted one (`dist/**` minus `!dist/**/*.map`) takes its paths back (see `outputs` below); one against a wildcard-rooted output (medusa's `*/**` minus `!src/**`) makes the task uncached, because the clean before exec would otherwise delete the sources — declare the exact outputs in a vx.config to cache it.
+- The mapping's gaps are the migration's gaps, reported as warnings by `vx lock` (and `vx lock --check`), never on a run, instead of `TODO(vx-migrate)` comments: `$TURBO_ROOT$` tasks, an env name vx cannot key that the run's environment sets (`FOO_?`, which Turbo reads literally), unknown turbo keys. A persistent task's readiness note (`readyWhen`) is reported only when something depends on it — with no dependent there is nothing to gate (refine printed it for 375 `dev` targets a run). `bunx @vzn/vx-migrate --dry` lists the same set once. Each gap is one line for every task that carries it, not one per task (n8n marks `dev` and `watch` persistent in most of its 84 packages; astro negates `vendor/**` in the outputs of 57 tasks). A per-package `{ "extends": false }` with nothing else is Turbo's opt-out and maps to no task; with keys, the task runs on those keys alone. A glob that climbs out of the package (`../../packages/app-store/*.generated.ts`) is re-anchored on the workspace root as a `workspaceFiles` glob. A negated output under a literal-rooted one (`dist/**` minus `!dist/**/*.map`) takes its paths back (see `outputs` below); one against a wildcard-rooted output (medusa's `*/**` minus `!src/**`) makes the task uncached, because the clean before exec would otherwise delete the sources — declare the exact outputs in a vx.config to cache it.
 - The cost is the stage's: on a 1,000-package workspace with no `vx.config` files the mapping loads in about 42 ms where 1,000 evaluated configs load in 22.
 - The mapping is kept in `<cache dir>/vx-migrate-turbo-mapping.json`, keyed on every `turbo.json` / `turbo.jsonc`, every package manifest, the mapper's own code and the environment variable names a wildcard can match (one in a Turbo config or Turbo's framework table) or core cannot key, so an unrelated variable keeps it; a run with none changed reads it instead of mapping (astro, 562 packages: ~40 ms of mapping against ~12 ms of key reads).
 - The mapping is read once per run, never once per process: under `vx watch`, a `package.json` script edit or a per-package `turbo.json` overlay edit is the next cycle's tasks. The root `turbo.json` is no task's input and lives in no project dir, so an edit to it is not a cycle — restart the watch.
@@ -62,7 +62,7 @@ Rules:
 - A transit node (Turbo's documented pattern, its with-vitest example: `transit: { dependsOn: ["^transit"] }` with no script anywhere, and `test: { dependsOn: ["transit"] }`) is a key-only task in each package that defines it: a keyed group (no command, nothing spawns) keyed on its inputs, with its `^transit` edge, so a dependant's `test` re-keys on its dependencies' sources as Turbo re-hashes it. A `^` task that some package has a script for, or that nothing depends on, is no transit node. A package without the script of a `^` task others run gets the same key-only task, as Turbo hashes a no-op node there: an edit to it re-keys its dependants. A `build` whose only edge is `^build` is not written: core gives every project with no `build` that node (solid's three script-less packages each got a `build` of their own). A dependency without the script whose own edges lack `^x` gets it too, so a `^x` stops there as Turbo's does (opencode's `build: { dependsOn: [] }`: core walked past to the builds below, which Turbo's `^build` never reaches).
 - `with` (tasks Turbo runs alongside, `web#dev` with `api#dev`): an edge to each sidecar that is persistent, so vx starts the task once the sidecar has spawned and runs the sidecar only when the task runs; a sidecar that ends would be waited for, so it is a todo instead, and a pair that names each other keeps one edge (two would be a cycle). A task with no script whose `with` names persistent sidecars (Turbo's with-tailwind example: `ui` has no `dev` script, its `dev` starts `dev:styles` and `dev:components`) is a group task that depends on them.
 - `inputs`: a structured entry (Turbo 2.11) is its `globs`, plus `**/*` with `withDefaults`, for `startup` and `jit` alike; `dependencyOutputs` adds none where the producer is cached (vx folds each dependency's key); from a `cache: false` producer (vercel/vercel's `//#generate:cache-keys`, which records the host) the named files, or its outputs, are a `cache.inputs.workspaceRuntime` probe, and `cache.inputs.tasks` leaves the producer out, so core answers the probe after it ran. Then: absent or `[]` → `**/*` (Turbo's default); `$TURBO_DEFAULT$` → `**/*`; exclusions alone narrow `**/*`; `$TURBO_ROOT$/<path>` → `cache.inputs.workspaceFiles` (negation kept); any other `$TURBO_ROOT$` use is a todo. `globalDependencies` and Turbo 1's `globalDotEnv` land in `workspaceFiles` too, and a task's Turbo 1 `dotEnv` in its `files`. Turbo 1's `$NAME` entries, in `globalDependencies` or a task's `dependsOn`, are env vars: they join `cache.inputs.env` and `exec.env.passThrough`. A package nested in the task's package (cal.com's apps inside `@calcom/app-store`) is hashed by Turbo with its parent, and core's globs stop at a project: each glob that reaches one is also listed in `cache.inputs.workspaceFiles`. Turbo's glob grammar is translated as Nx's is (`*.[jt]s` is `*.{[jt],j,t}s`); an input with no safe form widens to `**/*` with a todo. A wildcard `X/**` input, `!` or not, also lists `X`, as outputs do: Turbo's `**` matches zero segments, so `*/**` keys on the package-root files too. A `.env`-shaped input (`.env*`, `.env.local`, a task's Turbo 1 `dotEnv`, create-turbo's `globalDependencies: ["**/.env.*local"]`) is gitignored as a rule, so it is keyed by a probe that hashes the `.env` files it can name (`cache.inputs.runtime`) or, for a root entry, the files its root-relative globs name, hidden ones too, as Turbo's `*` matches them (`workspaceRuntime`; `**/<name>` is a `find -name` that skips `node_modules`, and another `**` walks the workspace), rather than as a file glob git never reports. A package whose `.env` globs all sit at its root gets a one-shell probe of that directory; one below the root walks the package.
-- `outputs`: `$TURBO_ROOT$/<path>` → `cache.outputs.workspaceFiles`; a negated output rides beside its positives and takes its paths back from the clean, the save and the restore (Next's `.next/**` minus `!.next/cache/**` keeps the cache), and one with no positive beside it takes back nothing and is dropped. Past its first segment an output takes Turbo's grammar (`dist/**/*.[cm]js`); the first stays a literal (a route directory). A wildcard `X/**` also lists `X`: Turbo's `**` matches zero segments, so medusa's `*/**` caches the package-root `tsconfig.tsbuildinfo` too (its `package.json` is taken back, below); a literal `dist/**` needs no `dist`. An output whose first segment is a wildcard (`**/*.d.ts`, medusa's `*/**`) stays cached, as in `nx()` (`turbo()` 2026-10-14): Turbo never cleans an output, vx cleans it before every run and every restore, and such a glob can reach the sources; core never cleans a committed file, and every untracked file it reaches is deleted, which each run's warnings name (`output "*/**": … every untracked file this glob reaches is deleted`). Negations beside it (`!src/**`) keep what they name. Without git the files cannot be told apart, and the task runs uncached with a todo. A glob that reaches no tracked kind gets no warning: one segment with a literal extension the package tracks no file of (`*.xml`), `**/<dir>/**` when the package tracks nothing under a directory of that name (vercel/ai's `**/dist/**`), and a first segment no tracked top-level entry matches (tldraw's `dist-*/**`). An output that covers the package's own `package.json` (trpc's client build lists it: the build rewrites `exports`) takes the manifest back with `!package.json` and keeps the cache, in `turbo()` as in `nx()` (owner, 2026-10-03): vx would otherwise delete it before every run. The build rewrites a file it may list as an input (`@vzn/vx-lockfile` lists `package.json`), so the Turbo mapping also sets `inputStability: { strategy: 'mutable' }` and an identical rewrite counts as unchanged. So does one that covers the package's vx.config; `turbo()` and `nx()` check the config the package has, and `vx-migrate` the one it writes, so sanity's `*.js` shims stay cached beside none. `nx()` keeps a wildcard-first output cached the same way (owner, 2026-10-03). A committed file under an output (typescript-eslint's `data/sponsors.json` in a cached `data`) needs nothing: core never cleans a file git tracks, so it survives and the task keeps its cache.
+- `outputs`: `$TURBO_ROOT$/<path>` → `cache.outputs.workspaceFiles`; a negated output rides beside its positives and takes its paths back from the clean, the save and the restore (Next's `.next/**` minus `!.next/cache/**` keeps the cache), and one with no positive beside it takes back nothing and is dropped. Past its first segment an output takes Turbo's grammar (`dist/**/*.[cm]js`); the first stays a literal (a route directory). A wildcard `X/**` also lists `X`: Turbo's `**` matches zero segments, so medusa's `*/**` caches the package-root `tsconfig.tsbuildinfo` too (its `package.json` is taken back, below); a literal `dist/**` needs no `dist`. An output whose first segment is a wildcard (`**/*.d.ts`, medusa's `*/**`) stays cached, as in `nx()` (`turbo()` 2026-10-14): Turbo never cleans an output, vx cleans it before every run and every restore, and such a glob can reach the sources; core never cleans a committed file, and every untracked file it reaches is deleted, which `vx lock`'s warnings name (`output "*/**": … every untracked file this glob reaches is deleted`). Negations beside it (`!src/**`) keep what they name. Without git the files cannot be told apart, and the task runs uncached with a todo. A glob that reaches no tracked kind gets no warning: one segment with a literal extension the package tracks no file of (`*.xml`), `**/<dir>/**` when the package tracks nothing under a directory of that name (vercel/ai's `**/dist/**`), and a first segment no tracked top-level entry matches (tldraw's `dist-*/**`). An output that covers the package's own `package.json` (trpc's client build lists it: the build rewrites `exports`) takes the manifest back with `!package.json` and keeps the cache, in `turbo()` as in `nx()` (owner, 2026-10-03): vx would otherwise delete it before every run. The build rewrites a file it may list as an input (`@vzn/vx-lockfile` lists `package.json`), so the Turbo mapping also sets `inputStability: { strategy: 'mutable' }` and an identical rewrite counts as unchanged. So does one that covers the package's vx.config; `turbo()` and `nx()` check the config the package has, and `vx-migrate` the one it writes, so sanity's `*.js` shims stay cached beside none. `nx()` keeps a wildcard-first output cached the same way (owner, 2026-10-03). A committed file under an output (typescript-eslint's `data/sponsors.json` in a cached `data`) needs nothing: core never cleans a file git tracks, so it survives and the task keeps its cache.
 - `env` / `passThroughEnv`: explicit names go to `cache.inputs.env` (env only) and `exec.env.passThrough` (both, plus both globals); a wildcard expands over the run's environment under `turbo()`, which maps where the tasks run (a new variable name such a wildcard matches maps afresh); the CLI, which writes for another environment, lists the names the task's package and its workspace dependencies spell (a root task: the whole repo; clerk's `E2E_*`), noted once per entry, and one nothing spells is a todo; `*` is the only wildcard, as in Turbo, so `\*`, a leading `\!`, `?` and `[` are literal: unkey's `NEXT_PUBLIC_\*` names one variable, which vx cannot key, so it is dropped and reported once for the workspace with the count of tasks naming it (openstatus's root `build` env `\*` had written one todo into each of 45 configs; `turbo()`: only when the run's environment sets it, as Turbo hashes nothing otherwise); and a `!` entry (openstatus' `!NEXT_PUBLIC_VERCEL_URL`) removes the names it matches from its list, with no todo, since vx matches no name it is not given. A name both a global list and the task's own list carry is listed once. A name that is no shell variable name (`p-q`) is keyed but left out of `exec.env.passThrough`, as `sh` drops it before the task runs.
 - Framework inference (Turbo hashes and passes Next's `NEXT_PUBLIC_*`, Vite's `VITE_*`, … for a package that depends on the framework): `turbo()` expands the prefix over the run's environment; the CLI writes the names the tracked source and `.env.example` of the package and its workspace dependencies spell (the bare prefix, as a `startsWith` test spells it, is none) (Next bundles theirs: cal.com's web, 23 alone, 58 with them), and a note asks for any only an installed dependency reads.
 
@@ -188,12 +188,12 @@ Once per run the plugin keys its snapshot (`<cache dir>/nx-project-graph.json`)
 ### What it does not do
 
 - A task the package's own `vx.config` already declares is left alone — the plugin fills, it never overwrites. Migrate a package by writing its config; the rest of the repo keeps running from the graph.
-- Each package-manager member is a project through core's `discover` stage (core finds only directories holding a `vx.config`), named by its `package.json`. An Nx project no workspace package matches — the root project, or an integrated repo's `project.json` library no package glob lists (analogjs) — is made a project the same way, by its `package.json` name or else its Nx name, and its targets attach there by directory; no `vx.config` is needed. One whose name a package already holds, or whose directory is gone, has nowhere to go and is reported once per run; run its targets with `nx`. A `^target` only such a project declares is no edge, as under Nx, and an explicit edge to one of its targets is dropped with a todo (the key misses it) rather than refusing the run. A negated output (`!{projectRoot}/dist/cache`) takes its path back from the positive ones (core's A-44). A cached target with no `outputs` takes what Nx caches for it: `options.outputPath` (each path of a list), or for `build` and `prepare` `dist/{projectRoot}` and `{projectRoot}/dist`; Nx's `{projectRoot}/build` and `{projectRoot}/public` are outputs too when git tracks nothing under them; one that holds a tracked file is a todo, since vx cleans an output before the run.
+- Each package-manager member is a project through core's `discover` stage (core finds only directories holding a `vx.config`), named by its `package.json`. An Nx project no workspace package matches — the root project, or an integrated repo's `project.json` library no package glob lists (analogjs) — is made a project the same way, by its `package.json` name or else its Nx name, and its targets attach there by directory; no `vx.config` is needed. One whose name a package already holds, or whose directory is gone, has nowhere to go and is reported by `vx lock`; run its targets with `nx`. A `^target` only such a project declares is no edge, as under Nx, and an explicit edge to one of its targets is dropped with a todo (the key misses it) rather than refusing the run. A negated output (`!{projectRoot}/dist/cache`) takes its path back from the positive ones (core's A-44). A cached target with no `outputs` takes what Nx caches for it: `options.outputPath` (each path of a list), or for `build` and `prepare` `dist/{projectRoot}` and `{projectRoot}/dist`; Nx's `{projectRoot}/build` and `{projectRoot}/public` are outputs too when git tracks nothing under them; one that holds a tracked file is a todo, since vx cleans an output before the run.
 - Nx adds an `nx-release-publish` target (`@nx/js:release-publish`) to every project with a `package.json`; it comes along as one `nx-exec` task per package, run only when asked (`vx run nx-release-publish --filter <pkg>`), and counts in `vx info`'s task total. A migration does not write it: Nx release's publish step skips a private package and a published version and rewrites `workspace:` ranges, which no one line does, so the report has one note naming the package manager's own `publish`.
 - `nx-exec` and `nx-env` must be on every task's PATH, which they are when `@vzn/vx-migrate` is a devDependency of the workspace (its bins land in `node_modules/.bin`); a plugin loaded by path warns once per run when they are not. Both load Nx from the workspace, so a repo run from an exported `graph` with no `node_modules/nx` warns once too.
 - A `dependsOn` entry's `params: "forward"` (the run's arguments) and `options: "forward"` (this target's options, its configuration's merged in) hand the dependency overrides, a different command than vx's one task per target: each is one todo per task, naming no dependency so a run's warnings group them (an atomized `e2e-ci` forwards to every spec), `options` only when there are options to forward.
 - Batch executors run one task per process; an executor that reads `context.taskGraph` under `NX_BUILDABLE_LIBRARIES_TASK_GRAPH` sees none and takes Nx's project-graph path.
-- The mapping's gaps are the migration's gaps, reported as warnings once per run for all the tasks that carry each one. `bunx @vzn/vx-migrate --dry --from nx` lists the same set once.
+- The mapping's gaps are the migration's gaps, reported as warnings by `vx lock`, once for all the tasks that carry each one. What this machine lacks to run them (the `nx-exec` bin, `node_modules/nx`, a graph export that failed) is warned on every run too. `bunx @vzn/vx-migrate --dry --from nx` lists the same set once.
 
 ## `nx-exec` — one Nx executor, one process
 
@@ -230,7 +230,7 @@ It is the one command a repo needs (`pnpx @vzn/vx-migrate` in a pnpm repo works
 - Native or keep, a remote cache the repo shows is declared: `turboCache()` for turbo.json's enabled `remoteCache`, a `turbo link`ed `.turbo/config.json` or a CI file (`.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/config.yml`) setting `TURBO_TOKEN`; `nxCache()` for one setting `NX_SELF_HOSTED_REMOTE_CACHE_SERVER`. The report names the file that showed it. Nx Cloud (`nxCloudId`, `nxCloudAccessToken`, the `nx-cloud` runner) is named instead: vx does not speak its wire.
 - With no `.vx/workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): the remote cache above, the `@vzn/vx-lockfile` factory for the lockfile (`pnpm()`, `bun()`, `npm()`, `yarn()`), `scheduleHistoryPlugin()`, and `github()` when `.github/workflows` exists, from `@vzn/vx-ci`, each installed beside `@vzn/vx` at vx-migrate's own version. Keep adds them to the file it writes, or to one already in that shape; any other workspace file is the user's and left alone. Native over a file vx wrote (a keep adoption's) rewrites it: `turbo()` and `nx()` go, since the configs written replace them, and the other plugins stay.
 - It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, the declared plugins' packages, and `@vzn/vx-migrate` for keep or when a written task runs its `nx-exec` or `nx-env` bin (`pnpm add -D -w`, `yarn add -D -W` on Yarn 1 and without `-W` on Yarn 2+, `bun add -d`, `npm install -D`). A package the root both lists and has installed at vx-migrate's own version is left alone; any other is installed at that version. Native removes a listed `@vzn/vx-migrate` when nothing written needs it (no `nx-exec` / `nx-env` task, no `turboCache()` or `nxCache()` left in the workspace file): `pnpm remove -w`, `yarn remove` (`-W` on Yarn 1), `bun remove`, `npm uninstall`. `--no-install` skips both.
-- Native, once the files are written, it ends with `vx lock`: `.vx/projects.lock.json` is written and the graph rules are checked, in one line before `next:`. A refusal is printed and the configs stay written (exit 0). `--no-install` skips it, since the plugins the workspace file declares are not installed yet, and `next:` then starts with `vx lock`.
+- Native, once the files are written, it ends with `vx lock`: `.vx/projects.lock.json` is written and the graph rules are checked, its line the report's `lock` row. A refusal prints above the report and the configs stay written (exit 0). `--no-install` skips it, since the plugins the workspace file declares are not installed yet, and `next` then starts with `vx lock`.
 
 A Lerna repo is an Nx one: Lerna 6+ runs `lerna run` on Nx's task runner over the graph `nx graph` exports, nx.json or not, so a `lerna.json` with no nx.json and no turbo.json is mapped from that graph, and keep writes the workspace file declaring `nx()`. Lerna is the installed one, else the root manifest's range; with neither, the lerna.json is another tool's (lerna-lite reads it too, and runs no Nx). A root whose scripts never `lerna run` runs its tasks another way and publishes with Lerna (webdriverio: `run-s`, `pnpm -r`), so its scripts stay the source. Not where Lerna runs its own runner: `useNx: false`, or Lerna 5 without `useNx: true`; those map their scripts. Beside turbo.json, Turbo runs the tasks and Lerna only publishes: turbo.json is the source.
 
@@ -240,6 +240,8 @@ Your `package.json` scripts are never edited. `--dry` installs nothing and says
 
 Every source hands a plan to core's migration seam (`applyMigration` from `@vzn/vx`), which renders, refuses to overwrite without `--force`, writes and reports. Anything a source cannot say becomes a `TODO(vx-migrate)` comment, never a silent wrong value.
 
+The report reads like a run's footer: a blank line, the `─ vx-migrate <version> ───` rule, then one dim label per row and each fact once: `from` (the source), `ran` (each install or removal command), `tasks` (clean in green, todo in yellow), `todo`, `files`, `kept`, `replaced`, `lock`, `note`, and last, after a blank line, `next` in bold. A terminal sees the install command while it runs, on a line the report replaces; the manager's own output prints only when it fails.
+
 ### Turbo
 
 Reads the root pipeline (`tasks` in Turbo 2, `pipeline` in Turbo 1), per-package `turbo.json` `extends` overlays and each package's scripts, through the same mapper `turbo()` runs live — so the written configs say what the plugin was doing. Turbo's global fields become a generated root `vx-preset.ts` each config imports and spreads: TypeScript composition replaces global config. A config that a `tsconfig*.json` in its directory or above (below the root) takes in, where that project is composite or sets `rootDir`, declares the values it uses instead: `tsc` refuses a file outside the package (TS6059, TS6307; withastro/astro's `scripts/` and the `performance/` project its `packages/astro/tsconfig.test.json` takes in). So does a task's `env` that several configs share (`buildEnv`), where inline it would repeat in every package (vercel/ai: 63 names, twice in each of ~100 configs, half the output). Turbo's `//#` root tasks are written to a `vx.config.ts` at the workspace root, which makes the root a project (core's D-39), and a package task's `//#x` edge reaches it. When a `.vx/workspace.ts` already exists without one, the report names the `@vzn/vx-lockfile` plugin for the repo's lockfile: Turbo keys each package on its own lockfile entries, and core keys every task on the whole file until a plugin claims it.
@@ -255,7 +257,7 @@ Reads the root pipeline (`tasks` in Turbo 2, `pipeline` in Turbo 1), per-package
 
 ### Nx
 
-Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `run.affectedBase`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
+Reads the **resolved** project graph only (`.nx/workspace-data/project-graph.json` when exported, else the one the workspace's own `nx graph` exports into a temp file, as `nx()` does; with no `node_modules/.bin/nx`, as in a fresh clone, it stops and names the repo manager's install), through the same mapper `nx()` runs live, executors aside (below). Targets Nx plugins infer at runtime are frozen as the snapshot saw them. `nx:run-commands` is the one shell line `nx()` runs (see [`nx:run-commands`](#nxrun-commands) above: where, parallel or in order, forwarded arguments, `env`, `readyWhen`) — storybook's `compile` is `cd ../../.. && node ./scripts/build/build-package.ts --cwd code/lib/cli`; a plain `command` is that shorthand; `nx:run-script` is the package's script body with its `pre<name>` / `post<name>` hooks folded in (or `yarn run <name>` when the body calls yarn's `run` builtin; an empty script is the placeholder with a todo), `nx:noop` is a group task; Nx 15–16's `@nrwl/workspace:run-commands` and `run-script` (and their `@nx/workspace:` names) are the `nx:` executors they re-exported; **an executor target is its `nx-exec` line**, as `nx()` runs it: the migrator translates no executor, so Nx and `@vzn/vx-migrate` stay installed until each such line is rewritten as the command it runs (a server executor Nx knows, `@nx/js:node` or a dev server, is still a persistent task). The report also says what `.vx/workspace.ts` still holds, as the Turbo migration does: the `nx()` a keep adoption declared, which keeps reading nx.json, and a lockfile with no `@vzn/vx-lockfile` plugin, where Nx keyed each project on the npm packages it depends on. A written command that still runs Nx itself (a run-commands `nx run b:build`, `npx nx test b`, a script's `nx exec -- tsc`) carries a TODO: it works only while Nx is installed. An Nx project no workspace glob lists (an integrated repo's `project.json` library) gets a `package.json` (`name`, `private`) where it has none, and a note names the directories to add to `workspaces` (or `pnpm-workspace.yaml`), so the package manager installs it and a lockfile plugin names it; the migrator never edits the root manifest. A repo with no `package.json` at all (Nx's `nx init` outside JS: Nx pinned in `.nx/installation`, projects as `project.json`) is migrated too, natively only: the root is the directory holding `nx.json`, the graph is exported by `.nx/installation`'s `nx`, each config writes the project's Nx `name`, every edge is the explicit `project#target` Nx's graph draws (a `^` edge needs a lockfile plugin, which has no lockfile to read), and `.vx/workspace.ts` declares no plugin, so nothing is installed and core runs the configs alone; `--keep` refuses, as `nx()` would have no `package.json` to install into, and an executor target's `nx-exec` line is a note to rewrite as a command. A target with `configurations` writes one task per configuration (`build`, `build:ci`). A project's Nx `tags` are written as its `tags`. Named inputs expand from `nx.json` when readable. An output path is kept as written, a `!` one too (`{projectRoot}/dist` → `dist`, `{projectRoot}/bin/tool` → `bin/tool`; one naming an unset `{options.x}` is dropped, as Nx drops it; a dotted `{options.outputPath.base}` walks the options, as Nx does; an extglob is put in vx's grammar: Next's inferred `.next/!(cache)/**/*` is `.next/*/**/*` with `!.next/cache/**/*`, `@(js|map)` is `{js,map}`, and a form with no vx spelling is dropped with a TODO): vx reads a bare path as the file or the whole tree under it, so a directory and an extensionless binary both save and restore. nx.json's `parallel`, `defaultBase` and `maxCacheSize`, which `nx()` applies live, are each a field of the `.vx/workspace.ts` it writes (`run.concurrency`, `run.affectedBase`, `cache.retention.maxSize`), read from nx.json alone, never the environment; beside a workspace file already there, or for a size vx cannot read (`1.5 GB`), each is a note naming the field to add. vx derives package edges from `package.json`; an Nx graph edge with no manifest path (`implicitDependencies`, a tsconfig path) becomes, for each `^target` of the dependant, an explicit `pkg#target` edge to what Nx's own walk reaches — each dependency that has the target, and through one that lacks it, its dependencies — so the order and the key are Nx's. The reverse too: where a project's manifest names a workspace package its Nx graph does not reach (an `implicitDependencies: ["!a"]` that breaks a manifest cycle), its `^target` becomes the explicit edges Nx draws, since vx's `^` would follow the manifest and bring the cycle back.
 
 ### Vite Task
 
@@ -297,7 +299,7 @@ package.json and re-run") rather than "no scripts" or "run vx init". A
 workspace whose globs match no `package.json` gets a note naming them
 (M-42); a nameless member, or two sharing a name, is matched and
 named on its own line instead (M-46). When such skipped scripts are all there
-is, the report opens `no package.json scripts became tasks.` rather than
+is, the report's `tasks` row reads `none: no package.json script became a task` rather than
 saying there are none (M-59). When `pnpm-workspace.yaml` lists the
 members and the root `package.json`'s `workspaces` lists other globs,
 the note names the unread list (M-51): pnpm reads only the yaml, while
@@ -386,7 +388,7 @@ config every later command refuses, and a `__proto__` script is written
 as a computed key, since a literal `__proto__:` sets the prototype. An
 existing `.vx/workspace.*` in any extension the loader reads (`.mts`
 included) is kept, and `--force` REPLACES a package's config of another
-extension (`replaced:` in the report) rather than writing a second one
+extension (`replaced` in the report) rather than writing a second one
 the loader would choose between by its order (item 1033). Without
 `--force`, it never overwrites: a package that already has a vx
 config keeps it, untouched, the rest get theirs, and the report lists

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-migrate",
-  "version": "0.0.637",
+  "version": "0.0.638",
   "license": "MIT",
   "description": "Adopt @vzn/vx from Turborepo, Nx or package.json scripts: run the repo unchanged, migrate it to vx.config.ts, and keep your Turbo or Nx remote cache",
   "keywords": [
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.637"
+    "@vzn/vx": "^0.0.638"
   },
   "repository": {
     "type": "git",

package/src/adopt.ts

@@ -168,7 +168,6 @@ export function install(
     pm === 'pnpm'
       ? `; if pnpm refused a version published within its minimumReleaseAge, list ${packages.join(', ')} under minimumReleaseAgeExclude in pnpm-workspace.yaml`
       : '',
-    ' (what the written files import)',
   )
 }
 
@@ -205,10 +204,12 @@ async function runManager(
   argv: string[],
   what: string,
   ranHint = '',
-  why = '',
 ): Promise<string> {
   const line = argv.join(' ')
-  process.stdout.write(`vx-migrate: ${line}${why}\n`)
+  // The report's `install` row says what ran; a terminal sees it while it
+  // runs, on a line the report then takes the place of.
+  const live = process.stdout.isTTY === true
+  if (live) process.stdout.write(`\n  ${line.slice(0, (process.stdout.columns ?? 80) - 4)} …`)
   // The manager's own output (progress, deprecations, audit, postinstalls)
   // is shown only when it fails: mid-init it buried the report (Growth's
   // first-run funnel F3, 2026-10-13).
@@ -237,6 +238,7 @@ async function runManager(
       failed = `: ${(e2 as Error).message}`
     }
   }
+  if (live) process.stdout.write('\r\x1b[2K\x1b[1A')
   if (code !== 0) {
     process.stderr.write(said)
     throw new UserError(

package/src/adoption-plugin.ts

@@ -29,7 +29,7 @@ async function spare(
     if (ids === undefined) todos.set(todo, (ids = []))
     ids.push(id)
   }
-  return { byName: mapping.byName, gaps: { notes: mapping.gaps.notes, todos } }
+  return { byName: mapping.byName, gaps: { ...mapping.gaps, todos } }
 }
 
 /**
@@ -97,7 +97,7 @@ export function adoptionPlugin(
       const mapped = await mapping!
       if (!warned) {
         warned = true
-        warnGaps(ctx.warn, plugin.name, mapped.gaps)
+        warnGaps(ctx.warn, plugin.name, mapped.gaps, ctx.lock)
       }
       const project = mapped.byName.get(ctx.name)
       if (project === undefined) return

package/src/mapping-cache.ts

@@ -61,6 +61,7 @@ interface Held {
   ][]
   readonly notes: string[]
   readonly todos: [string, string[]][]
+  readonly live: string[]
 }
 
 /** `map()`, or the mapping it returned last under the same `parts`. */
@@ -78,7 +79,7 @@ export async function cachedMapping(
   if (held?.key === key) {
     return {
       byName: new Map(held.byName),
-      gaps: { notes: held.notes, todos: new Map(held.todos) },
+      gaps: { notes: held.notes, todos: new Map(held.todos), live: held.live },
     }
   }
   const mapping = await map()
@@ -93,6 +94,7 @@ export async function cachedMapping(
     ]),
     notes: [...mapping.gaps.notes],
     todos: [...mapping.gaps.todos].map(([todo, ids]) => [todo, [...ids]]),
+    live: [...mapping.gaps.live],
   }
   // Best-effort, and whole or absent: a reader never sees half a file, and
   // a cache dir it cannot write costs the next run a mapping, not the run.

package/src/migrate-nx.ts

@@ -3,7 +3,7 @@
 
 import { stat } from 'node:fs/promises'
 import path from 'node:path'
-import { type MigrationFormat, type MigrationPlan } from '@vzn/vx'
+import { type GeneratedProject, type MigrationFormat, type MigrationPlan } from '@vzn/vx'
 import type { PackageMeta } from './packages.js'
 import { mapNxWorkspace, nxSizeText, parseNxGraph, readNxJson } from './nx/nx-map.js'
 import { spareTrackedOutputs, trackedFiles, trackedKinds } from './tracked-outputs.js'
@@ -23,6 +23,8 @@ export async function migrateNx(
   snapshot = path.join(root, NX_GRAPH_REL),
   /** This run writes `.vx/workspace.ts`, with nx.json's run settings as fields. */
   writesWorkspace = false,
+  /** No package.json anywhere: each config names its project and holds every edge. */
+  bare = false,
 ): Promise<MigrationPlan> {
   const graph = parseNxGraph(await Bun.file(snapshot).text(), path.relative(root, snapshot))
   const tracked = await trackedFiles(root)
@@ -48,14 +50,20 @@ export async function migrateNx(
     runner: 'nx',
     keys: (lock) => `Nx keys each project on the npm packages it depends on in ${lock}`,
   })
-  const unlisted = await unlistedProjects(root, metas, mapped.projects)
+  const unlisted = bare
+    ? { manifests: [], notes: bareNotes(mapped.projects) }
+    : await unlistedProjects(root, metas, mapped.projects)
+  if (bare) for (const p of mapped.projects) explicitOnly(p)
   return {
     headerNotes: [
-      'migrating from the resolved project-graph snapshot — plugin-inferred targets ' +
-        'are frozen as static config; `nx:run-commands` targets are their shell lines, and ' +
-        'every other executor runs as itself through `nx-exec` (keep Nx and @vzn/vx-migrate ' +
-        'installed until those targets are rewritten as commands); targets with `.env` files ' +
-        'run through `nx-env`',
+      bare
+        ? 'migrating from the resolved project-graph snapshot — plugin-inferred targets ' +
+          'are frozen as static config; `nx:run-commands` targets are their shell lines'
+        : 'migrating from the resolved project-graph snapshot — plugin-inferred targets ' +
+          'are frozen as static config; `nx:run-commands` targets are their shell lines, and ' +
+          'every other executor runs as itself through `nx-exec` (keep Nx and @vzn/vx-migrate ' +
+          'installed until those targets are rewritten as commands); targets with `.env` files ' +
+          'run through `nx-env`',
       ...adopted,
     ],
     projects: mapped.projects.map((p) =>
@@ -74,6 +82,38 @@ export async function migrateNx(
   }
 }
 
+/**
+ * A project with no manifest is named by its path unless its config names
+ * it, and a `^` edge follows the lockfile plugin's package edges, which a
+ * repo with no package.json has none of: the config keeps Nx's name, and
+ * the explicit edges the mapper drew from Nx's graph are every edge.
+ */
+function explicitOnly(p: GeneratedProject): void {
+  p.writeName = true
+  for (const t of p.tasks) {
+    const deps = t.task?.['dependsOn']
+    if (!Array.isArray(deps)) continue
+    const kept = deps.filter((d) => typeof d !== 'string' || !d.startsWith('^'))
+    // A group keeps its list, as `dropUnheldDeps` keeps one.
+    if (kept.length > 0 || t.task!['exec'] === undefined) t.task!['dependsOn'] = kept
+    else delete t.task!['dependsOn']
+  }
+}
+
+/** `nx-exec` and `nx-env` are this package's bins, and a repo with no package.json cannot install it. */
+function bareNotes(projects: readonly GeneratedProject[]): string[] {
+  const ids = projects.flatMap((p) =>
+    p.tasks.flatMap((t) => {
+      const cmd = (t.task?.['exec'] as { command?: unknown } | undefined)?.command
+      return typeof cmd === 'string' && /^nx-(exec|env) /.test(cmd) ? [`${p.name}#${t.name}`] : []
+    }),
+  )
+  if (ids.length === 0) return []
+  return [
+    `${ids.join(', ')} run${ids.length === 1 ? 's' : ''} through nx-exec or nx-env, @vzn/vx-migrate's bins, which a repo with no package.json cannot install: rewrite ${ids.length === 1 ? 'it' : 'them'} as commands`,
+  ]
+}
+
 /**
  * Nx projects no workspace glob lists (an integrated repo's `project.json`
  * libraries): core finds a project only by a listed package.json, so a

package/src/migrate.ts

@@ -20,9 +20,11 @@ import {
   applyMigration,
   findWorkspaceRoot,
   isUserError,
+  VERSION,
   type MigrationFormat,
   type MigrationPlan,
   UserError,
+  ui,
 } from '@vzn/vx'
 import { migrateScripts } from './migrate-scripts.js'
 import type { LoadReads } from './package-fs.js'
@@ -39,7 +41,7 @@ import {
 import { relPosix } from './paths.js'
 import { REMOTE_CACHE, remoteCacheNote } from './remote-cache.js'
 import { migrateNx, NX_GRAPH_REL, nxWorkspaceFields } from './migrate-nx.js'
-import { exportGraph } from './nx/export-graph.js'
+import { exportGraph, nxBin } from './nx/export-graph.js'
 import { readNxJson } from './nx/nx-map.js'
 import {
   type AdoptionMode,
@@ -148,12 +150,18 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
     return 1
   }
   const reads: LoadReads = new Map()
+  // An Nx repo with no package.json (Nx pinned in `.nx/installation`):
+  // nothing is installable, so its configs run on core alone.
+  let bare = false
   const root = await migrationRoot(process.cwd(), reads).catch(async (err: unknown) => {
-    throw isUserError(err) ? await noRootReason(process.cwd(), err) : err
+    const nx = isUserError(err) ? nxRootWithoutManifest(process.cwd()) : undefined
+    if (nx === undefined) throw isUserError(err) ? await noRootReason(process.cwd(), err) : err
+    bare = true
+    return nx
   })
-  const workspace = await loadPackageWorkspace(root, reads)
+  const workspace = bare ? { root, packageGlobs: [] } : await loadPackageWorkspace(root, reads)
   const nameless: string[] = []
-  const metas = await discoverPackages(workspace, nameless)
+  const metas = bare ? [] : await discoverPackages(workspace, nameless)
 
   const turboFile = await turboConfigFile(root)
   const hasTurbo = turboFile !== null
@@ -214,13 +222,24 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
     metas.some((m) => m.configPath !== null) &&
     !readFileSync(path.join(root, existing), 'utf8').includes(`${runner}(`)
   ) {
-    process.stdout.write(
-      `vx is already set up here (${existing} and the projects' vx.config files); --force regenerates them from ${runnerFile}.\n\nnext: ${adoptionNext(root, runner, runnerFile, ['@vzn/vx'])}\n`,
+    ui.print(
+      'out',
+      ui.report(`vx-migrate ${VERSION}`, [
+        ['kept', `${existing} and the projects' vx.config files`],
+        ['note', `vx is already set up here; --force regenerates them from ${runnerFile}`],
+        null,
+        ['next', adoptionNext(root, runner, runnerFile, ['@vzn/vx'])],
+      ]),
     )
     return 0
   }
+  if (bare && parsed.mode === 'keep') {
+    throw new UserError(
+      '--keep: nx() is a plugin to install, and this Nx repo has no package.json to install it in; drop --keep to write vx.config files',
+    )
+  }
   const mode =
-    runner === 'vite-task'
+    runner === 'vite-task' || bare
       ? 'native'
       : (parsed.mode ?? (await askMode(runner, lerna ? 'lerna.json' : undefined, parsed.dry)))
   if (mode === 'keep' && runner !== 'vite-task') return keep(root, runner, runnerFile, parsed)
@@ -248,14 +267,14 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
   } else if (runner === 'nx') {
     if (hasGraph) {
       source = NX_GRAPH_REL
-      plan = await migrateNx(root, metas, format, undefined, writesWorkspace)
+      plan = await migrateNx(root, metas, format, undefined, writesWorkspace, bare)
     } else {
       // Modern Nx stores the graph in SQLite, so the JSON snapshot exists only
       // when exported. The workspace's own nx exports it, as `nx()` does, into
       // a temp file; the user ran that step by hand until 2026-10-01.
       // A fresh clone: the export's own reason names the plugin's `graph`
       // option, which the CLI does not take.
-      if (!existsSync(path.join(root, 'node_modules', '.bin', 'nx'))) {
+      if (nxBin(root) === undefined) {
         throw new UserError(
           `nx is not installed here (no node_modules/.bin/nx), and vx-migrate reads the graph it exports — ` +
             `run \`${packageManagerOf(root, process.env['npm_config_user_agent'])} install\`, then vx-migrate again`,
@@ -272,7 +291,7 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
           )
         }
         source = 'nx graph'
-        plan = await migrateNx(root, metas, format, snapshot, writesWorkspace)
+        plan = await migrateNx(root, metas, format, snapshot, writesWorkspace, bare)
       } finally {
         await rm(tmp, { recursive: true, force: true })
       }
@@ -294,14 +313,15 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
     ) ||
       plan.extraFiles.some((f) => existsSync(path.join(root, f.relPath))))
   const kept = (adopted ?? []).filter((p) => !ADOPTION_PLUGINS.has(`${p.pkg}#${p.factory}`))
-  const plugins = writesWorkspace
-    ? [
-        ...kept,
-        ...workspacePlugins(root, runner === 'vite-task' ? undefined : runner).filter(
-          (p) => !kept.some((k) => k.factory === p.factory),
-        ),
-      ]
-    : []
+  const plugins =
+    writesWorkspace && !bare
+      ? [
+          ...kept,
+          ...workspacePlugins(root, runner === 'vite-task' ? undefined : runner).filter(
+            (p) => !kept.some((k) => k.factory === p.factory),
+          ),
+        ]
+      : []
   let workspaceText: string | undefined
   if (writesWorkspace) {
     const fields =
@@ -340,33 +360,34 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
     runner === 'vite-task'
       ? undefined
       : remoteCacheNote(root, runner, finalWorkspace.includes(`${REMOTE_CACHE[runner]}(`))
-  const headerNotes = refused
-    ? []
-    : [
-        ...(existingWorkspace !== undefined && workspaceText !== undefined
-          ? await rewriteWorkspace(root, existingWorkspace, workspaceText, adopted!, parsed.dry)
-          : []),
-        ...(await prepareRepo(
-          root,
-          [
-            ...new Set([
-              '@vzn/vx',
-              ...(needsSelf ? ['@vzn/vx-migrate'] : []),
-              ...plugins.map((p) => p.pkg),
-            ]),
-          ],
-          parsed,
-          needsSelf ? [] : ['@vzn/vx-migrate'],
-        )),
-        ...(cacheNote === undefined ? [] : [cacheNote]),
-      ]
+  const steps: Step[] =
+    refused || bare
+      ? []
+      : [
+          ...(existingWorkspace !== undefined && workspaceText !== undefined
+            ? await rewriteWorkspace(root, existingWorkspace, workspaceText, adopted!, parsed.dry)
+            : []),
+          ...(await prepareRepo(
+            root,
+            [
+              ...new Set([
+                '@vzn/vx',
+                ...(needsSelf ? ['@vzn/vx-migrate'] : []),
+                ...plugins.map((p) => p.pkg),
+              ]),
+            ],
+            parsed,
+            needsSelf ? [] : ['@vzn/vx-migrate'],
+          )),
+        ]
   return applyMigration({
     root,
     metas,
     plan,
     source,
     verb: 'vx-migrate',
-    notes: headerNotes,
+    steps,
+    notes: refused || bare || cacheNote === undefined ? [] : [cacheNote],
     dry: parsed.dry,
     json: parsed.json === true,
     force: parsed.force,
@@ -380,13 +401,24 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
  * Core's `vx lock`, run where the configs were written: the step `vx init`
  * ends with, through the core this repo resolves.
  */
-async function lockWorkspace(root: string): Promise<number> {
-  return await Bun.spawn([process.execPath, '--no-install', coreBin(root), 'lock'], {
+async function lockWorkspace(root: string): Promise<{ code: number; said: string }> {
+  const p = Bun.spawn([process.execPath, '--no-install', coreBin(root), 'lock'], {
     cwd: root,
-    stdio: ['ignore', 'inherit', 'inherit'],
-  }).exited
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const [out, err, code] = await Promise.all([
+    new Response(p.stdout).text(),
+    new Response(p.stderr).text(),
+    p.exited,
+  ])
+  // A success's warnings print above the report; a refusal is said whole.
+  if (code === 0) process.stderr.write(err)
+  return { code, said: code === 0 ? out : out + err }
 }
 
+/** A report row: what the tool did, e.g. `['ran', 'bun add -d …']`. */
+type Step = readonly [label: string, value: string]
+
 /** The `vx` entry of the core this repo resolves. */
 function coreBin(root: string): string {
   // A resolve that misses from a directory with no node_modules is an
@@ -427,7 +459,7 @@ const ADOPTION_PLUGINS = new Set(['@vzn/vx-migrate#turbo', '@vzn/vx-migrate#nx']
 
 /**
  * A `--keep` adoption's workspace file, written over for a native one.
- * Returns the report's line; writes nothing under `--dry`.
+ * Returns the report's row; writes nothing under `--dry`.
  */
 async function rewriteWorkspace(
   root: string,
@@ -435,41 +467,41 @@ async function rewriteWorkspace(
   text: string,
   before: readonly WorkspacePlugin[],
   dry: boolean,
-): Promise<string[]> {
+): Promise<Step[]> {
   if (readFileSync(path.join(root, file), 'utf8') === text) return []
   const dropped = before.filter((p) => ADOPTION_PLUGINS.has(`${p.pkg}#${p.factory}`))
   const names = dropped.map((p) => `${p.factory}()`).join(', ')
   if (dry)
-    return [`would ${dropped.length > 0 ? `drop ${names} from` : 'rewrite'} ${file} (dry run)`]
+    return [['config', `would ${dropped.length > 0 ? `drop ${names} from` : 'rewrite'} ${file}`]]
   await Bun.write(path.join(root, file), text)
-  return [`${dropped.length > 0 ? `dropped ${names} from` : 'rewrote'} ${file}`]
+  return [['config', `${dropped.length > 0 ? `dropped ${names} from` : 'rewrote'} ${file}`]]
 }
 
 /**
  * Install what the written files import and remove what they no longer
- * do. Returns the report's lines; changes nothing under `--dry`.
+ * do. Returns the report's rows; changes nothing under `--dry`.
  */
 async function prepareRepo(
   root: string,
   wanted: readonly string[],
   args: MigrateArgs,
   unwanted: readonly string[] = [],
-): Promise<string[]> {
+): Promise<Step[]> {
   if (args.noInstall === true) return []
-  const notes: string[] = []
+  const steps: Step[] = []
   const version = ownVersion()
   const missing = missingPackages(root, wanted, version)
   if (missing.length > 0) {
-    if (args.dry) notes.push(`would install ${missing.join(' ')} (dry run)`)
-    else notes.push(`installed ${missing.join(' ')} (${await install(root, missing, version)})`)
+    steps.push(
+      args.dry ? ['install', missing.join(' ')] : ['ran', await install(root, missing, version)],
+    )
   }
   // Last: the package removed may be the one running this.
   const listed = listedPackages(root, unwanted)
   if (listed.length > 0) {
-    if (args.dry) notes.push(`would remove ${listed.join(' ')} (dry run)`)
-    else notes.push(`removed ${listed.join(' ')} (${await uninstall(root, listed)})`)
+    steps.push(args.dry ? ['remove', listed.join(' ')] : ['ran', await uninstall(root, listed)])
   }
-  return notes
+  return steps
 }
 
 /**
@@ -502,13 +534,13 @@ async function keep(
   const extended = before === undefined ? null : extendWorkspaceFile(before, all)
   const text = before === undefined ? renderWorkspaceFile(all, format) : (extended ?? before)
   const declares = before === undefined || extended !== null
-  for (const note of await prepareRepo(
+  const steps = await prepareRepo(
     root,
     [...new Set(['@vzn/vx', '@vzn/vx-migrate', ...(declares ? all.map((p) => p.pkg) : [])])],
     args,
-  )) {
-    ;(args.json ? process.stderr : process.stdout).write(`vx-migrate: ${note}\n`)
-  }
+  )
+  if (args.json)
+    for (const [label, value] of steps) process.stderr.write(`vx-migrate: ${label}: ${value}\n`)
   const ignore = existsSync(path.join(root, '.vx', '.gitignore')) ? [] : ['.vx/.gitignore']
   if (!args.dry) {
     if (before === undefined) {
@@ -524,14 +556,15 @@ async function keep(
       ? undefined
       : remoteCacheNote(root, runner, text.includes(`${cache}(`))
   const added = before === undefined ? [] : undeclared(before, all).map((p) => `${p.factory}()`)
-  const wrote =
+  const wrote: Step =
     before === undefined
-      ? args.dry
-        ? `would write ${name} (dry run, nothing written).`
-        : `wrote ${name}.`
+      ? ['files', [name, ...ignore].join('\n')]
       : text === before
-        ? `${existing} already declares ${runner}().`
-        : `${args.dry ? 'would declare' : 'declared'} ${added.join(', ')} in ${existing}.`
+        ? ['kept', `${existing} (declares ${runner}())`]
+        : [
+            'config',
+            `${args.dry ? 'would declare' : 'declared'} ${added.join(', ')} in ${existing}`,
+          ]
   const next = adoptionNext(root, runner, source, [
     ...new Set(['@vzn/vx', '@vzn/vx-migrate', ...(declares ? all.map((p) => p.pkg) : [])]),
   ])
@@ -556,17 +589,40 @@ async function keep(
     )
     return 0
   }
-  process.stdout.write(
-    `${args.dry && before === undefined ? `── ${name} ──\n${text}\n` : ''}` +
-      `vx-migrate: ${source} found — ${runner}() from @vzn/vx-migrate, a temporary start until vx init --native writes native config.\n` +
-      `${wrote}\n${cacheLine === undefined ? '' : `${cacheLine}\n`}\n`,
-  )
+  if (args.dry && before === undefined) process.stdout.write(`── ${name} ──\n${text}\n`)
   // A run reads only the lock; with the plugins installed it is written
   // now, else `next` names `vx lock` after the install.
-  const locks = !args.dry && !next.includes(' lock && ')
-  const code = locks ? await lockWorkspace(root) : 0
-  process.stdout.write(`${locks ? '\n' : ''}next: ${next}\n`)
-  return code
+  const lock = !args.dry && !next.includes(' lock && ') ? await lockWorkspace(root) : undefined
+  if (lock !== undefined && lock.code !== 0) process.stderr.write(lock.said)
+  const rows: ui.FieldRow[] = [
+    ['from', `${source}, run by ${runner}() from @vzn/vx-migrate`],
+    ...(args.dry ? [['dry run', 'nothing written'] as const] : []),
+    ...steps,
+    wrote,
+    ...(lock === undefined ? [] : [lockRow(lock)]),
+    [
+      'note',
+      'a temporary start: vx init --native writes native config',
+      ...(cacheLine === undefined ? [] : [cacheLine]),
+    ],
+    null,
+    [
+      'next',
+      lock === undefined || lock.code === 0 ? next : `fix the above, then vx lock and ${next}`,
+    ],
+  ]
+  ui.print('out', ui.report(`vx-migrate ${VERSION}`, rows))
+  return lock?.code ?? 0
+}
+
+/** `vx lock`'s outcome as the report's row. */
+function lockRow(lock: { code: number; said: string }): ui.FieldRow {
+  return [
+    'lock',
+    lock.code === 0
+      ? lock.said.trim().replace(/^✓ vx lock\s+/, '')
+      : ui.tone('error', 'not written'),
+  ]
 }
 
 /** `.vx/.gitignore`'s text, as core writes it: the machine-local cache stays out of git. */
@@ -670,12 +726,8 @@ async function scripts(
     plan,
     source: 'package.json scripts',
     verb: 'vx-migrate',
-    notes: [
-      ...noMembers,
-      ...(await unreadWorkspaces(root, workspace.packageGlobs)),
-      ...unmapped,
-      ...installed,
-    ],
+    notes: [...noMembers, ...(await unreadWorkspaces(root, workspace.packageGlobs)), ...unmapped],
+    steps: installed,
     unmapped: unmapped.length > 0,
     ...(unreached.length > 0 ? { emptyReason: unreachedHint(unreached, root) } : {}),
     dry: args.dry,
@@ -776,6 +828,18 @@ async function migrationRoot(cwd: string, reads: LoadReads): Promise<string> {
   return marked
 }
 
+/**
+ * The nearest directory up to the git top-level holding nx.json, for a
+ * repo with no package.json: Nx's `nx init` outside JS pins Nx in
+ * `.nx/installation` and finds projects by `project.json`.
+ */
+function nxRootWithoutManifest(cwd: string): string | undefined {
+  for (let d = cwd; ; d = path.dirname(d)) {
+    if (existsSync(path.join(d, 'nx.json'))) return d
+    if (existsSync(path.join(d, '.git')) || path.dirname(d) === d) return undefined
+  }
+}
+
 /**
  * Lerna 6+ runs `lerna run` on Nx's task runner over the graph `nx graph`
  * exports, nx.json or not, unless lerna.json says `useNx: false`; Lerna 5

package/src/nx/export-graph.ts

@@ -1,7 +1,7 @@
 // The resolved Nx graph, exported by the workspace's own nx: `nx()` keys and
 // keeps it, `vx-migrate --from nx` maps it once.
 
-import { readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 
@@ -11,10 +11,9 @@ import path from 'node:path'
  * daemon up the export is served from memory, without it Nx computes.
  */
 export async function exportGraph(root: string, snapshot: string): Promise<string | null> {
-  const linked = path.join(root, 'node_modules', '.bin', 'nx')
-  const bin = (await Bun.file(linked).exists()) ? linked : lernasNx(root)
+  const bin = nxBin(root)
   if (bin === undefined) {
-    return `no ${path.relative(root, linked)} — install nx, or export a graph with \`nx graph --file=<path>\` and pass it as graph: '<path>'`
+    return `no node_modules/.bin/nx — install nx, or export a graph with \`nx graph --file=<path>\` and pass it as graph: '<path>'`
   }
   // `discover` runs before the run opens (and makes) the cache dir.
   await mkdir(path.dirname(snapshot), { recursive: true })
@@ -30,6 +29,18 @@ export async function exportGraph(root: string, snapshot: string): Promise<strin
   return `nx graph --file exited ${code}${tail ? `: ${tail}` : ''}`
 }
 
+/**
+ * The workspace's own nx: the linked bin, else where Nx's wrapper installs
+ * it in a repo with no package.json (`.nx/installation`), else Lerna's.
+ */
+export function nxBin(root: string): string | undefined {
+  for (const dir of [root, path.join(root, '.nx', 'installation')]) {
+    const bin = path.join(dir, 'node_modules', '.bin', 'nx')
+    if (existsSync(bin)) return bin
+  }
+  return lernasNx(root)
+}
+
 /**
  * The nx Lerna 6+ runs on, from Lerna's own dependencies: pnpm links only
  * a root's direct dependencies into `node_modules/.bin`, so a Lerna repo

package/src/nx/index.ts

@@ -404,7 +404,8 @@ async function index(
   trackedFiles: () => Promise<readonly string[] | null>,
   executors: NxExecutors | undefined,
 ): Promise<AdoptionMapping> {
-  const notes = [...loadNotes]
+  const notes: string[] = []
+  const live = [...loadNotes]
   const tracked = await trackedFiles()
   const configs = new Map(
     metas.flatMap((m) =>
@@ -458,7 +459,7 @@ async function index(
     if (!uses(bin)) continue
     loadsNx = true
     if (!(await Bun.file(path.join(root, 'node_modules', '.bin', bin)).exists())) {
-      notes.push(
+      live.push(
         `${what} through \`${bin}\`, which is not in node_modules/.bin — add ` +
           "@vzn/vx-migrate to the workspace's devDependencies so its bin is on every task's PATH",
       )
@@ -470,7 +471,7 @@ async function index(
     loadsNx &&
     !(await Bun.file(path.join(root, 'node_modules', 'nx', 'package.json')).exists())
   ) {
-    notes.push(
+    live.push(
       'nx-exec and nx-env load Nx from the workspace, and node_modules/nx is not there — ' +
         'install nx, or those tasks fail',
     )
@@ -480,6 +481,7 @@ async function index(
     gaps: collectGaps(
       mapped.projects.filter((p) => byName.has(p.name)),
       notes,
+      live,
     ),
   }
 }

package/src/plugin-gaps.ts

@@ -1,5 +1,6 @@
-// What a mapping could not say, reported once per run by the plugin that
-// runs it live. One line per DISTINCT gap, not one per task: n8n has a
+// What a mapping could not say, reported once by `vx lock`, the pass that
+// checks configs (a run checks nothing, M 2026-10-15). What this machine
+// lacks to run the mapping (a bin, a graph export) is said on runs too. One line per DISTINCT gap, not one per task: n8n has a
 // `dev` and a `watch` in most of its 84 packages, and astro's `build`
 // carries the same `!vendor/**` output in every package — the per-task
 // form was a hundred identical lines before the first frame (2026-09-11).
@@ -15,10 +16,16 @@ export interface Gaps {
   readonly notes: readonly string[]
   /** Every task-level gap, keyed on its text, to the `pkg#task` ids that carry it. */
   readonly todos: ReadonlyMap<string, readonly string[]>
+  /** This machine's state, not the configs': said on every run as well. */
+  readonly live: readonly string[]
 }
 
 /** The gaps of a mapping, indexed for the one-line-per-gap report. */
-export function collectGaps(projects: readonly MappedProject[], notes: readonly string[]): Gaps {
+export function collectGaps(
+  projects: readonly MappedProject[],
+  notes: readonly string[],
+  live: readonly string[] = [],
+): Gaps {
   const todos = new Map<string, string[]>()
   for (const project of projects) {
     for (const t of project.tasks) {
@@ -29,10 +36,18 @@ export function collectGaps(projects: readonly MappedProject[], notes: readonly
       }
     }
   }
-  return { notes, todos }
+  return { notes, todos, live }
 }
 
-export function warnGaps(warn: (line: string) => void, pluginName: string, gaps: Gaps): void {
+/** At `vx lock` every gap; on a run only the live notes. */
+export function warnGaps(
+  warn: (line: string) => void,
+  pluginName: string,
+  gaps: Gaps,
+  lock: boolean,
+): void {
+  for (const note of gaps.live) warn(`[${pluginName}] ${note}`)
+  if (!lock) return
   for (const note of gaps.notes) warn(`[${pluginName}] ${note}`)
   for (const [todo, ids] of gaps.todos) {
     if (ids.length === 1) {