@vzn/vx-migrate 0.0.521 → 0.0.523

package/README.md

@@ -212,7 +212,8 @@ bunx @vzn/vx-migrate --help    # the usage, exit 0
 It is the one command a repo needs (`pnpx @vzn/vx-migrate` in a pnpm repo works the same):
 
 - In a terminal it asks which adoption you want: **native** (the default, a `vx.config.ts` per package) or **keep** (the workspace file `vx init` writes, declaring `turbo()` or `nx()`). `--native` / `--keep` answer it; with no terminal (CI, a pipe) it is native.
-- It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, plus `@vzn/vx-migrate` for keep (`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 already listed or installed is left alone; `--no-install` skips it.
+- With no `vx.workspace.*` yet, it writes one declaring the plugins the repo calls for (`src/workspace-plugins.ts`): 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 `vx init` writes, or to one already in that shape; any other workspace file is the user's and left alone.
+- It installs what the written files import with the repo's own manager (`packageManager`, else the lockfile): `@vzn/vx`, plus `@vzn/vx-migrate` for keep (the declared plugins are built into the vx binary, so none is installed) (`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. `--no-install` skips it.
 
 Your `package.json` scripts are never edited. `--dry` installs nothing and says what it would install.
 
@@ -222,7 +223,7 @@ Your `package.json` scripts are never edited. `--dry` installs nothing and says
 
 ### 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. 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. The report names the `@vzn/vx-lockfile` plugin for the repo's lockfile when `vx.workspace.ts` declares none: Turbo keys each package on its own lockfile entries, and core keys every task on the whole file until a plugin claims it.
+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. 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.
 
 | Turborepo                           | vx                                                                                                |
 | ----------------------------------- | ------------------------------------------------------------------------------------------------- |

package/package.json

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

package/src/adopt.ts

@@ -85,26 +85,57 @@ export function installArgv(
   }
 }
 
-/** The packages a mode's files import that the root neither lists nor has installed. */
-export function missingPackages(root: string, mode: AdoptionMode): string[] {
+/**
+ * This package's release version; null in the source tree (`0.0.0`), where
+ * nothing is pinned. Every @vzn package releases in lockstep, and each
+ * plugin's peer is `^<version>`, which on 0.0.x is that version alone.
+ */
+export function ownVersion(): string | null {
+  const v = (
+    JSON.parse(readText(path.join(import.meta.dir, '..', 'package.json')) || '{}') as {
+      version?: unknown
+    }
+  ).version
+  return typeof v === 'string' && v !== '0.0.0' ? v : null
+}
+
+/**
+ * The `wanted` packages the root does not both list and have installed
+ * (at `version`, given one). Either alone is not adopted: a reset
+ * package.json leaves node_modules behind, and a listing is not an
+ * install; on solidjs/solid vx-migrate 0.0.512 skipped @vzn/vx that
+ * package.json did not list (owner, 2026-10-06).
+ */
+export function missingPackages(
+  root: string,
+  wanted: readonly string[],
+  version: string | null = null,
+): string[] {
   const pj = JSON.parse(readText(path.join(root, 'package.json')) || '{}') as Record<
     string,
     Record<string, unknown> | undefined
   >
   const listed = (name: string) =>
     ['dependencies', 'devDependencies'].some((f) => pj[f]?.[name] !== undefined)
-  const wanted = mode === 'keep' ? ['@vzn/vx', '@vzn/vx-migrate'] : ['@vzn/vx']
-  return wanted.filter(
-    (p) => !listed(p) && !existsSync(path.join(root, 'node_modules', p, 'package.json')),
-  )
+  return wanted.filter((p) => {
+    if (!listed(p)) return true
+    const installed = readText(path.join(root, 'node_modules', p, 'package.json'))
+    if (installed === '') return true
+    if (version === null) return false
+    return (JSON.parse(installed) as { version?: unknown }).version !== version
+  })
 }
 
-/** Install `packages` with the repo's manager, its output on the terminal. */
-export async function install(root: string, packages: readonly string[]): Promise<string> {
+/** Install `packages` (at `version`, given one) with the repo's manager, its output on the terminal. */
+export async function install(
+  root: string,
+  packages: readonly string[],
+  version: string | null = null,
+): Promise<string> {
   const argv = installArgv(
     root,
     packageManagerOf(root, process.env['npm_config_user_agent']),
-    packages,
+    version === null ? packages : packages.map((p) => `${p}@${version}`),
   )
   const line = argv.join(' ')
   process.stdout.write(`vx-migrate: ${line}\n`)

package/src/migrate-turbo.ts

@@ -350,10 +350,7 @@ function renderPreset(
   // would otherwise splice into a malformed, unloadable `vx-preset.ts`.
   const arr = (xs: string[]): string => `[${xs.map(quote).join(', ')}]`
   const lines = [
-    // The same name the configs carry (`verb` in index.ts): `vx migrate` is
-    // no verb, and a reader who typed it got `unknown command`.
-    '// Generated by `vx-migrate` from turbo.json. TypeScript composition',
-    "// replaces turbo's global fields: each vx.config.ts imports these",
+    "// TypeScript composition replaces turbo's global fields: each vx.config.ts imports these",
     '// arrays and spreads them into the matching task fields.',
   ]
   if (inputs.length > 0) {

package/src/migrate.ts

@@ -9,7 +9,7 @@
 // (`applyMigration`) renders, guards, writes and reports, so what this
 // package writes reads exactly like what `vx init` writes.
 
-import { existsSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
@@ -30,10 +30,18 @@ import {
   install,
   missingPackages,
   MODE_QUESTION,
+  ownVersion,
   parseModeAnswer,
 } from './adopt.js'
 import { migrateTurbo } from './migrate-turbo.js'
 import { turboConfigFile } from './turbo/turbo-map.js'
+import {
+  extendWorkspaceFile,
+  undeclared,
+  renderWorkspaceFile,
+  workspaceFileAt,
+  workspacePlugins,
+} from './workspace-plugins.js'
 
 export interface MigrateArgs {
   dry: boolean
@@ -193,7 +201,22 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
           existsSync(path.join(p.dir, configName))),
     ) ||
       plan.extraFiles.some((f) => existsSync(path.join(root, f.relPath))))
-  const headerNotes = refused ? [] : await prepareRepo(root, 'native', parsed)
+  // No workspace file yet: write one declaring the plugins the repo calls
+  // for, and drop the note that told the user to declare the lockfile one.
+  const plugins = workspaceFileAt(root) === undefined ? workspacePlugins(root) : []
+  if (plugins.length > 0) {
+    plan = {
+      ...plan,
+      headerNotes: plan.headerNotes.filter((n) => !n.includes('from @vzn/vx-lockfile')),
+      extraFiles: [
+        ...plan.extraFiles,
+        { relPath: `vx.workspace.${format}`, contents: renderWorkspaceFile(plugins, format) },
+      ],
+    }
+  }
+  const headerNotes = refused
+    ? []
+    : await prepareRepo(root, ['@vzn/vx', ...plugins.map((p) => p.pkg)], parsed)
   return applyMigration({
     root,
     metas,
@@ -221,12 +244,17 @@ async function askMode(runner: 'turbo' | 'nx', dry: boolean): Promise<AdoptionMo
  * Install what the written files import. Returns the report's line;
  * installs nothing under `--dry`.
  */
-async function prepareRepo(root: string, mode: AdoptionMode, args: MigrateArgs): Promise<string[]> {
+async function prepareRepo(
+  root: string,
+  wanted: readonly string[],
+  args: MigrateArgs,
+): Promise<string[]> {
   const notes: string[] = []
-  const missing = args.noInstall === true ? [] : missingPackages(root, mode)
+  const version = ownVersion()
+  const missing = args.noInstall === true ? [] : 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)})`)
+    else notes.push(`installed ${missing.join(' ')} (${await install(root, missing, version)})`)
   }
   return notes
 }
@@ -248,7 +276,19 @@ async function keep(
       '--keep with --from nx: turbo.json is here too, and vx init adopts it first',
     )
   }
-  for (const note of await prepareRepo(root, 'keep', args)) {
+  // The plugins go into the file `vx init` writes, or into one already
+  // here in that shape; another shape is the user's, and left alone.
+  const existing = workspaceFileAt(root)
+  const plugins =
+    existing === undefined ||
+    extendWorkspaceFile(readFileSync(path.join(root, existing), 'utf8'), []) !== null
+      ? workspacePlugins(root)
+      : []
+  for (const note of await prepareRepo(
+    root,
+    ['@vzn/vx', '@vzn/vx-migrate', ...plugins.map((p) => p.pkg)],
+    args,
+  )) {
     process.stdout.write(`vx-migrate: ${note}\n`)
   }
   // A resolve that misses from a directory with no node_modules is an
@@ -260,8 +300,19 @@ async function keep(
   const flags = [args.dry && '--dry', args.force && '--force', args.mjs && '--mjs'].filter(
     (f): f is string => typeof f === 'string',
   )
-  return Bun.spawn(
+  const code = await Bun.spawn(
     [process.execPath, '--no-install', path.join(path.dirname(core), 'bin.ts'), 'init', ...flags],
     { cwd: root, stdio: ['inherit', 'inherit', 'inherit'] },
   ).exited
+  const written = workspaceFileAt(root)
+  if (code !== 0 || args.dry || written === undefined || plugins.length === 0) return code
+  const file = path.join(root, written)
+  const text = readFileSync(file, 'utf8')
+  const extended = extendWorkspaceFile(text, plugins)
+  if (extended !== null && extended !== text) {
+    await Bun.write(file, extended)
+    const names = undeclared(text, plugins).map((p) => `${p.factory}()`)
+    process.stdout.write(`vx-migrate: declared ${names.join(', ')} in ${written}\n`)
+  }
+  return code
 }

package/src/workspace-notes.ts

@@ -18,6 +18,12 @@ const LOCKFILES: ReadonlyArray<readonly [file: string, plugin: string]> = [
   ['yarn.lock', 'yarn'],
 ]
 
+/** The lockfile at `root` and the `@vzn/vx-lockfile` factory that claims it. */
+export function lockfilePlugin(root: string): { file: string; factory: string } | undefined {
+  const lock = LOCKFILES.find(([file]) => existsSync(path.join(root, file)))
+  return lock === undefined ? undefined : { file: lock[0], factory: lock[1] }
+}
+
 export interface AdoptedTool {
   /** The adoption plugin `vx init` declares: `turbo`, `nx`. */
   readonly plugin: string
@@ -43,11 +49,11 @@ export async function adoptedToolNotes(root: string, tool: AdoptedTool): Promise
       )
     break
   }
-  const lock = LOCKFILES.find(([file]) => existsSync(path.join(root, file)))
-  if (lock !== undefined && !declared.includes('@vzn/vx-lockfile'))
+  const lock = lockfilePlugin(root)
+  if (lock !== undefined && !new RegExp(`\\b${lock.factory}\\s*\\(`).test(declared))
     notes.push(
-      `${tool.keys(lock[0])}; vx keys every task on the whole ` +
-        `file, so a dependency bump re-runs them all. Declare ${lock[1]}() from @vzn/vx-lockfile ` +
+      `${tool.keys(lock.file)}; vx keys every task on the whole ` +
+        `file, so a dependency bump re-runs them all. Declare ${lock.factory}() from @vzn/vx-lockfile ` +
         "in vx.workspace.ts to key each task on its package's dependency closure",
     )
   return notes

package/src/workspace-plugins.ts

@@ -0,0 +1,89 @@
+// The plugins a migrated workspace declares, from what the repo shows
+// (owner, 2026-10-06: "install and migrate fully … use the plugins"). Each
+// is inert where it does not apply, so declaring one costs a run nothing,
+// and each is installed beside vx at vx-migrate's own version (plugins
+// pin their core peer to the release they shipped with).
+
+import { existsSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import { lockfilePlugin } from './workspace-notes.js'
+
+export interface WorkspacePlugin {
+  readonly pkg: string
+  readonly factory: string
+}
+
+export function workspacePlugins(root: string): WorkspacePlugin[] {
+  const out: WorkspacePlugin[] = []
+  const lock = lockfilePlugin(root)
+  if (lock !== undefined) out.push({ pkg: '@vzn/vx-lockfile', factory: lock.factory })
+  out.push({ pkg: '@vzn/vx-schedule-history', factory: 'scheduleHistoryPlugin' })
+  if (existsSync(path.join(root, '.github', 'workflows')))
+    out.push({ pkg: '@vzn/vx-ci', factory: 'github' })
+  return out
+}
+
+/** The workspace file at `root`, in any extension the loader reads. */
+export function workspaceFileAt(root: string): string | undefined {
+  return readdirSync(root).find((n) => /^vx\.workspace\.(ts|mts|js|mjs|cts|cjs)$/.test(n))
+}
+
+/** `plugins` that `text` does not already call. */
+export function undeclared(text: string, plugins: readonly WorkspacePlugin[]): WorkspacePlugin[] {
+  return plugins.filter((p) => !new RegExp(`\\b${p.factory}\\s*\\(`).test(text))
+}
+
+function importLines(plugins: readonly WorkspacePlugin[]): string[] {
+  return plugins.map((p) => `import { ${p.factory} } from '${p.pkg}'`)
+}
+
+function entries(plugins: readonly WorkspacePlugin[], indent: string): string[] {
+  return plugins.map((p) => `${indent}${p.factory}(),`)
+}
+
+/** `vx.workspace.<format>` declaring `plugins`. */
+export function renderWorkspaceFile(
+  plugins: readonly WorkspacePlugin[],
+  format: 'ts' | 'mjs',
+): string {
+  return [
+    ...(format === 'ts' ? ["import type { WorkspaceConfig } from '@vzn/vx/config'"] : []),
+    ...importLines(plugins),
+    '',
+    'export default {',
+    '  plugins: [',
+    ...entries(plugins, '    '),
+    '  ],',
+    `}${format === 'ts' ? ' satisfies WorkspaceConfig' : ''}`,
+    '',
+  ].join('\n')
+}
+
+/**
+ * Add `plugins` to the file `vx init` writes (`export default { plugins:
+ * [turbo()] }`); null for any other shape, which is left alone. A plugin
+ * the file already calls is not added twice.
+ */
+export function extendWorkspaceFile(
+  text: string,
+  plugins: readonly WorkspacePlugin[],
+): string | null {
+  const m = /^export default \{ plugins: \[([^\]\n]*)\] \}/m.exec(text)
+  if (m === null) return null
+  const added = undeclared(text, plugins)
+  if (added.length === 0) return text
+  const head = text.slice(0, m.index).trimEnd()
+  const tail = text.slice(m.index + m[0].length)
+  const kept = m[1]!.trim()
+  return [
+    head,
+    ...importLines(added),
+    '',
+    'export default {',
+    '  plugins: [',
+    ...(kept === '' ? [] : [`    ${kept},`]),
+    ...entries(added, '    '),
+    '  ],',
+    `}${tail}`,
+  ].join('\n')
+}