@vzn/vx-migrate 0.0.635 → 0.0.637

package/src/migrate-scripts.ts

@@ -0,0 +1,1261 @@
+// package.json scripts → vx tasks: the source for a workspace that comes
+// from nowhere (no turbo.json, no nx). `vx init` is this mapper.
+//
+// Scripts carry a command and nothing else, so the mapping is honest about
+// what it cannot know: every task gets `exec.command` verbatim; `build`
+// gets the conventional `dependsOn: ['^build']` and `test` / `typecheck`
+// wait for `build` when the package has one (`lint` does not); a dev-server
+// shaped script becomes persistent. Caching is opt-in and needs declared
+// inputs AND outputs, which a script cannot tell us — so NO task gets a
+// cache block; `build` carries a TODO showing the block to add. Until
+// 2026-09-04 `build` was emitted with whole-project inputs and EMPTY
+// outputs "to fill in": that is not an uncached task but a no-output one —
+// it hits on unchanged inputs and skips the build with nothing to restore,
+// so a deleted `dist` stayed deleted under a green `up-to-date` run
+// (reproduced on the init walkthrough). A block that guessed `dist/**`
+// would restore the wrong tree for every package that writes somewhere
+// else, and a wrong restore is the worst failure vx has.
+//
+// Two npm conventions are mapped rather than copied, because copying them
+// loses behaviour: `pre<x>` / `post<x>` hooks, which npm runs around `x`
+// without being named, are folded into `x`'s command in that order (a
+// standalone `prebuild` task is one `vx run build` never runs — and the
+// hook is usually `rimraf dist`); and a script that is nothing but
+// `<pm> run <other>` becomes a GROUP over `<other>`, so the graph sees the
+// dependency instead of a package-manager subprocess it cannot cache.
+// Where the manager runs no such hooks (Yarn 2+, D-31; npm or pnpm told
+// not to, D-33) `prebuild` is a script like any other.
+
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import {
+  foldScriptHooks,
+  type GeneratedProject,
+  type GeneratedTask,
+  type MigrationPlan,
+  PERSISTENT_TODO,
+  pruneOrphanPersistentNotes,
+  taskNameProblem,
+} from '@vzn/vx'
+import type { PackageMeta } from './packages.js'
+import { relPosix } from './paths.js'
+
+/**
+ * Task names that conventionally never exit. Every mapper guesses the same
+ * way from a name — a source that SAYS a task is long-running (turbo's
+ * `persistent: true`, an Nx dev-server executor) is believed instead.
+ */
+const PERSISTENT_TASK_NAMES: ReadonlySet<string> = new Set([
+  'dev',
+  'start',
+  'serve',
+  'watch',
+  'preview',
+])
+
+/**
+ * Where a framework's build writes by default, for the cache TODO: the
+ * hint said `dist/**` to every build, `next build` included, which writes
+ * `.next`. Each tool's documented default; anything else keeps `dist/**`.
+ */
+const BUILD_OUTPUTS: readonly [RegExp, readonly string[]][] = [
+  [/\snext build\s/, ['.next/**', '!.next/cache/**']],
+  [/\snux[ti] build\s/, ['.output/**']],
+  [/\s(?:remix|react-router|react-scripts|docusaurus) build\s/, ['build/**']],
+  [/\sgatsby build\s/, ['public/**']],
+  [/\s(?:storybook build|build-storybook)\s/, ['storybook-static/**']],
+]
+
+/** A directory a TODO may name: relative, plain, no hidden or tool dir. */
+const OUTPUT_DIR = /^(?:\.\/)?((?![./])[\w@-][\w@./-]*?)\/?$/
+
+/**
+ * The directory the command says it writes, when no tool above names one:
+ * an out-dir flag (`tsc --outDir lib`, `babel -d lib`), else the
+ * directories it cleans first (`del-cli distribution`, `rimraf dist
+ * types`). ky's build writes `distribution/`, and the TODO said `dist/**`
+ * (D-90). A file (`tsconfig.tsbuildinfo`) and `node_modules` are no output.
+ */
+function namedOutputs(command: string): string[] | undefined {
+  const dir = (w: string | undefined): string | undefined => {
+    const m = w === undefined ? null : OUTPUT_DIR.exec(w.replace(/^(["'])(.*)\1$/, '$2'))
+    if (m === null) return undefined
+    const d = m[1]!
+    return /\.[a-z]+$/i.test(d) || d.split('/').includes('node_modules') ? undefined : d
+  }
+  const flag = /\s(?:--outDir|--out-dir|--outdir|-d)[\s=](\S+)/.exec(` ${command} `)
+  const out = dir(flag?.[1])
+  if (out !== undefined) return [`${out}/**`]
+  for (const segment of command.split(/[;&|()]+/)) {
+    const words = segment.trim().split(/\s+/)
+    const at =
+      words[0] === 'rimraf' || words[0] === 'del-cli' || words[0] === 'del'
+        ? 1
+        : words[0] === 'rm' || (words[0] === 'shx' && words[1] === 'rm')
+          ? words.indexOf('rm') + 1
+          : -1
+    if (at < 0) continue
+    const args = words.slice(at).filter((w) => !w.startsWith('-'))
+    // A dir the command makes again (kit's `rm -rf ./missing_ids && mkdir
+    // ./missing_ids && vite build`) is a scratch dir it prepares, not output.
+    const made = new Set([...command.matchAll(/\bmkdir\s+(?:-p\s+)?(\S+)/g)].map((m) => dir(m[1])))
+    const dirs = args
+      .map(dir)
+      .filter((d): d is string => d !== undefined)
+      .filter((d) => !made.has(d))
+    // Every cleaned path a directory vx can name, or the guess is not this.
+    return dirs.length > 0 && dirs.length === args.filter((w) => !/\.[a-z]+$/i.test(w)).length
+      ? dirs.map((d) => `${d}/**`)
+      : undefined
+  }
+  return undefined
+}
+
+/** The cache block the task that builds `command` should declare, as a TODO on it. */
+export function cacheTodo(command: string): string {
+  // Padded, separators as spaces: `next build && …` and `(next build)` match.
+  const words = ` ${command.replace(/[;&|()]/g, ' ')} `
+  const hit = BUILD_OUTPUTS.find(([re]) => re.test(words))
+  const outputs = (hit?.[1] ?? namedOutputs(command) ?? ['dist/**']).map((o) => `'${o}'`).join(', ')
+  return `cache: add \`cache: { inputs: { files: ['src/**'] }, outputs: { files: [${outputs}] } }\` with this package's real inputs and outputs — without it the task always runs and every file here, what it writes included, folds into the key its dependents fold; a block with EMPTY outputs would be a cached no-op, not an uncached task`
+}
+
+// `lint` is not here: a linter reads sources, and an edge to `build`
+// serialises the two for nothing (the init walkthrough, 2026-09-04).
+const AFTER_BUILD = new Set(['test', 'typecheck', 'check', 'e2e'])
+const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepublishOnly|install)$/
+
+/**
+ * The script a command delegates to when it is NOTHING but a package-manager
+ * invocation of another script: `npm run x`, `pnpm x`, `yarn run x`, `bun run
+ * x`, plus npm's bare `npm test` / `npm start`. Flags, arguments or a chain
+ * make it a real command again, which is left verbatim.
+ */
+export function delegatedScript(command: string): string | null {
+  const m =
+    /^(?:(?:npm run|(pnpm|pn|yarn|bun)(?: (run))?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+      command.trim(),
+    )
+  if (m === null) return null
+  if (m[4] !== undefined) return m[4]
+  const [, alias, run, name] = m
+  // `pn` is pnpm's own short name (pnpm 11; pnpm/pnpm's scripts run it).
+  const manager = alias === 'pn' ? 'pnpm' : alias
+  // Bare, the manager's own command wins over a script of that name:
+  // `bun test` is Bun's test runner and `bun build` its bundler, never the
+  // `test` / `build` script, and a group over the script ran the wrong
+  // thing (item 908). `pnpm test` and `yarn test` do run the script.
+  if (manager !== undefined && run === undefined && OWN_COMMANDS[manager]!.has(name!)) return null
+  return name!
+}
+
+/** What `<manager> <name>`, with no `run`, runs as the manager's own command. */
+// Listing a name that runs the script only keeps the command verbatim, so
+// each set leans wide; missing one of the manager's own made a group over
+// a script the manager never runs (D-32: `pnpm docs` opened npm's docs page,
+// `bun deploy` answered "reserved", `yarn check` verified dependencies).
+const OWN_COMMANDS: Readonly<Record<string, ReadonlySet<string>>> = {
+  // `bun --help`, Bun 1.4.2, the short aliases, and the names it reserves
+  // or runs itself (probed: `bun lint` runs the script).
+  bun: new Set(
+    'run test x repl exec install i add a remove rm update audit dedupe prune outdated link unlink publish patch pm info why build init create c upgrade feedback list deploy config login logout whoami help'.split(
+      ' ',
+    ),
+  ),
+  // pnpm 10.33.0's `commandNames`, and the npm commands it passes through
+  // to npm whatever the scripts say.
+  pnpm: new Set(
+    'add approve-builds audit bin c cache cat-file cat-index ci clean-install completion config create dedupe deploy dislink dlx doctor env exec fetch find-hash get i ic ignored-builds import init install install-clean install-test it la licenses link list ll ln ls m multi outdated pack patch patch-commit patch-remove prune publish rb rebuild recursive remove restart rm root run run-script self-update server set setup store un uni uninstall unlink up update upgrade why access adduser bugs deprecate dist-tag docs edit find home info issues login logout owner ping prefix profile pkg repo s se search set-script show star stars team token unpublish unstar v version view whoami xmas help'.split(
+      ' ',
+    ),
+  ),
+  // `yarn help`, Yarn 1.22.22 and Yarn 4.5.0: one set for both.
+  yarn: new Set(
+    'access add audit autoclean bin cache check config constraints create dedupe dlx exec explain files generate-lock-entry global help import info init install licenses link list login logout node npm outdated owner pack patch patch-commit plugin policies publish rebuild remove run search set stage tag team unlink unplug up upgrade upgrade-interactive version versions why workspace workspaces'.split(
+      ' ',
+    ),
+  ),
+}
+
+/**
+ * The package manager that owns `dir`, when it runs `pre` / `post` hooks
+ * around a script; null when it runs none. The manager is the nearest `packageManager` field or
+ * lockfile, and its settings are read beside it, as each reads them for a
+ * member too. Probed with a `prebuild` / `build` / `postbuild` trio: Yarn
+ * 2+ runs none (D-31); npm runs none under `ignore-scripts=true` in
+ * `.npmrc`; pnpm runs none under `enable-pre-post-scripts=false` there or
+ * `enablePrePostScripts: false` in `pnpm-workspace.yaml` (D-33); Bun and
+ * Yarn 1 run them whatever those say. No manager found is npm's default.
+ */
+function runsScriptHooks(dir: string, memo: Map<string, Owner>): string | null {
+  const { manager, at } = ownerOf(dir, memo)
+  const read = (f: string): string | undefined => {
+    try {
+      return readFileSync(path.join(at, f), 'utf8')
+    } catch {
+      return undefined
+    }
+  }
+  const npmrc = read('.npmrc') ?? ''
+  const set = (key: string, value: string): boolean =>
+    new RegExp(`^\\s*${key}\\s*=\\s*${value}\\s*$`, 'm').test(npmrc)
+  const runs =
+    manager === 'berry'
+      ? false
+      : manager === 'npm'
+        ? !set('ignore-scripts', 'true')
+        : manager === 'pnpm'
+          ? !set('enable-pre-post-scripts', 'false') && !pnpmSkipsHooks(read('pnpm-workspace.yaml'))
+          : true
+  return runs ? manager : null
+}
+
+/**
+ * `enablePrePostScripts: false` in `pnpm-workspace.yaml`, read as pnpm reads
+ * it, as YAML: a line regex missed `false # hooks off` and a flow mapping,
+ * which pnpm 10 honours, and folded hooks pnpm does not run.
+ */
+function pnpmSkipsHooks(yaml: string | undefined): boolean {
+  if (yaml === undefined) return false
+  try {
+    const parsed = Bun.YAML.parse(yaml) as { enablePrePostScripts?: unknown } | null
+    return parsed?.enablePrePostScripts === false
+  } catch {
+    return false
+  }
+}
+
+/** The package manager that owns a directory, and the directory that says so. */
+interface Owner {
+  manager: string
+  at: string
+}
+
+/**
+ * The nearest `packageManager` field or lockfile from `dir` up: `berry` for
+ * Yarn 2+, `yarn` for Yarn 1, else the manager's name; none found is npm.
+ */
+function ownerOf(dir: string, memo: Map<string, Owner>): Owner {
+  const known = memo.get(dir)
+  if (known !== undefined) return known
+  const read = (f: string): string | undefined => {
+    try {
+      return readFileSync(path.join(dir, f), 'utf8')
+    } catch {
+      return undefined
+    }
+  }
+  let manager: string | undefined
+  try {
+    // A byte-order mark is stripped, as npm, pnpm and discovery strip it:
+    // JSON.parse threw on one and the field went unread.
+    const manifest = (read('package.json') ?? '').replace(/^\uFEFF/, '')
+    const pm = (JSON.parse(manifest) as { packageManager?: unknown }).packageManager
+    // A manager vx knows nothing of (zod's `nub@0.8.3`) says nothing about
+    // hooks: the lockfile beside it does, and "nub ran `postbuild`" was a
+    // claim nothing had checked (D-96).
+    if (typeof pm === 'string' && /^(npm|pnpm|yarn|bun)@/.test(pm))
+      manager = /^yarn@([2-9]|\d{2,})/.test(pm) ? 'berry' : pm.split('@')[0]
+  } catch {}
+  if (manager === undefined) {
+    const yarnLock = read('yarn.lock')
+    if (yarnLock !== undefined) manager = yarnLock.includes('\n__metadata:') ? 'berry' : 'yarn'
+    else if (existsSync(path.join(dir, 'pnpm-lock.yaml'))) manager = 'pnpm'
+    else if (existsSync(path.join(dir, 'package-lock.json'))) manager = 'npm'
+    else if (['bun.lock', 'bun.lockb'].some((f) => existsSync(path.join(dir, f)))) manager = 'bun'
+  }
+  const up = path.dirname(dir)
+  const owner =
+    manager !== undefined
+      ? { manager, at: dir }
+      : up === dir
+        ? { manager: 'npm', at: dir }
+        : ownerOf(up, memo)
+  memo.set(dir, owner)
+  return owner
+}
+
+/**
+ * Yarn 2+ runs a script in its own shell, where `run <script>` is `yarn
+ * run <script>`; vx's shell has no `run`, and 23 of berry's scripts
+ * (`run build:zip:worker`, `run test:unit packages/…`) mapped to tasks
+ * that failed "command not found" (D-92). Spelled out, at the head of
+ * each `&&` / `||` / `;` / `|` segment.
+ */
+function berryRun(command: string): string {
+  return command.replace(/(^|&&|\|\||[;|(])(\s*)run(?=\s)/g, '$1$2yarn run')
+}
+
+const MANIFEST_IMPORT = "import pkg from './package.json' with { type: 'json' }"
+
+/**
+ * The `$npm_*` variables a command reads. Every manager sets them for a
+ * script (probed: npm, pnpm, bun and yarn printed the version, the name
+ * and the script's name) and vx sets none, so a migrated `echo
+ * $npm_package_version` printed nothing (D-34). The name and version are
+ * read from the manifest at evaluation, so a bump reaches them; the event
+ * is the script's own name, which a folded hook does not share.
+ */
+function npmEnv(
+  command: string,
+  script: string,
+  folded: boolean,
+): { define: Record<string, unknown>; unset: string[]; readsManifest: boolean } {
+  const define: Record<string, unknown> = {}
+  const unset: string[] = []
+  let readsManifest = false
+  for (const [, v] of command.matchAll(/\$\{?(npm_[A-Za-z0-9_]+)/g)) {
+    if (v! in define || unset.includes(v!)) continue
+    if (v === 'npm_package_name' || v === 'npm_package_version') {
+      define[v] = { raw: v === 'npm_package_name' ? 'pkg.name' : 'pkg.version' }
+      readsManifest = true
+    } else if (v === 'npm_lifecycle_event' && !folded) define[v] = script
+    else unset.push(v!)
+  }
+  return { define, unset, readsManifest }
+}
+
+/**
+ * A script that never exits by design (D-40): a `watch` segment in its
+ * name (`build:watch`, `watch-css`), a `--watch` flag, `tsc -w` /
+ * `rollup -w`, or nodemon. Run as a plain task it held its dependents
+ * forever. A bare `-w` elsewhere is not read: `npm run x -w pkg` is a
+ * workspace.
+ */
+function isWatcher(name: string, command: string): boolean {
+  if (name.split(/[:\-_.]/).includes('watch')) return true
+  return (
+    /(?:^|\s)--watch(?:All)?(?:[=\s]|$)/.test(command) ||
+    /\b(?:tsc|rollup)\b[^&|;]*\s-w(?:\s|$)/.test(command) ||
+    /(?:^|[\s&|;])nodemon\b/.test(command)
+  )
+}
+
+/** A server run alone (`serve website`, `http-server`), or a tool's own server verb. */
+const SERVERS = new Set(['serve', 'http-server', 'live-server', 'sirv', 'webpack-dev-server'])
+const SERVER_TOOLS = new Set([
+  'vite',
+  'next',
+  'astro',
+  'nuxt',
+  'nuxi',
+  'remix',
+  'react-router',
+  'docusaurus',
+  'storybook',
+  'netlify',
+  'wrangler',
+  'webpack',
+  'expo',
+  'react-native',
+])
+const SERVER_VERBS = new Set(['dev', 'serve', 'start', 'preview'])
+const LAUNCHERS = new Set(['cross-env', 'npx', 'bunx', 'exec', 'dlx'])
+
+/**
+ * A command that runs a server (D-91): docusaurus's `serve website` and
+ * `netlify dev` mapped as one-shot tasks, so a dependent waited forever and
+ * a server that exits on stdin EOF ended at once. Read per `&&` segment,
+ * past env assignments and launchers; a quoted string is another tool's
+ * argument (`start-server-and-test 'vite preview' …` exits).
+ */
+function servesCommand(command: string): boolean {
+  for (const segment of foreground(command.replace(/"[^"]*"|'[^']*'/g, ' '))) {
+    const words = segment
+      .trim()
+      .split(/\s+/)
+      .filter((w) => w !== '')
+    let i = 0
+    while (
+      i < words.length &&
+      (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!) ||
+        LAUNCHERS.has(words[i]!) ||
+        words[i]!.startsWith('-') ||
+        (/^(pnpm|npm|yarn)$/.test(words[i]!) && LAUNCHERS.has(words[i + 1] ?? '')))
+    ) {
+      // A launcher's `--package <name>` / `-p <name>` names what to install,
+      // not the program: docusaurus's `pnpm dlx --package netlify-cli netlify
+      // dev` read `netlify-cli` as the program (D-112).
+      i += words[i] === '--package' || words[i] === '-p' ? 2 : 1
+    }
+    const [program, verb] = [words[i], words[i + 1]]
+    if (program === undefined) continue
+    if (SERVERS.has(program)) return true
+    if (SERVER_TOOLS.has(program) && verb !== undefined && SERVER_VERBS.has(verb)) return true
+    if (program === 'vite' && (verb === undefined || verb.startsWith('-'))) return true
+  }
+  return false
+}
+
+/**
+ * Whether script `name` never exits: by name, as a watcher, as a server, or
+ * running such a script of its own package by name (docusaurus's
+ * `start:baseUrl`: `cross-env BASE_URL=… pnpm start`) or through a runner.
+ */
+function isPersistent(
+  name: string,
+  scripts: Readonly<Record<string, unknown>>,
+  seen: Set<string> = new Set(),
+): boolean {
+  const own = scripts[name]
+  if (typeof own !== 'string' || seen.has(name)) return false
+  seen.add(name)
+  if (PERSISTENT_TASK_NAMES.has(name) || isWatcher(name, own) || servesCommand(own)) return true
+  // Through a runner too: `concurrently "npm:web" "npm:api"` and `run-p web
+  // api` over two servers mapped as one-shot tasks (D-113).
+  const text = Object.entries(scripts).filter(
+    (e): e is [string, string] => typeof e[1] === 'string',
+  )
+  return foreground(own).some((segment) =>
+    scriptRefs(segment, text).some((ref) => isPersistent(ref, scripts, seen)),
+  )
+}
+
+/** The `&&` / `;` / `|` segments of a command, less those it backgrounds with a single `&`. */
+function foreground(command: string): string[] {
+  return command
+    .split(/&&|\|\||[;|()]/)
+    .flatMap((part) => part.split('&').slice(-1))
+    .filter((segment) => segment.trim() !== '')
+}
+
+function scriptsOf(meta: PackageMeta): Record<string, unknown> {
+  // package.json is a boundary: `scripts` is whatever the file holds. A
+  // string or an array would enumerate its indices as script names.
+  const raw = (meta.packageJson as unknown as { scripts?: unknown }).scripts
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {}
+  return raw as Record<string, unknown>
+}
+
+/**
+ * A `build` that only delegates (`build: pnpm run compile`) is a group over
+ * its target, and the `^build` edge every `build` carries belongs on the
+ * task that does the work: the group ran `compile` with no edge at all, so
+ * a package compiled before the ones it imports had built (item 907). On
+ * the group itself it would not hold — the group waits on both, `compile`
+ * on neither. Followed through a chain of groups to the first command,
+ * which takes the cache TODO too: a group has no command to cache, and the
+ * TODO a delegating `build` never got was the one the header promised
+ * (item 1045).
+ */
+function upstreamBuildOnWorker(tasks: GeneratedTask[]): void {
+  const byName = new Map(tasks.map((t) => [t.name, t]))
+  const seen = new Set<string>()
+  let at = byName.get('build')
+  while (at?.task !== undefined && at.task !== null && !('exec' in at.task)) {
+    if (seen.has(at.name)) return
+    seen.add(at.name)
+    const deps = at.task['dependsOn']
+    at = Array.isArray(deps) ? byName.get(String(deps[0])) : undefined
+  }
+  if (at === undefined || at.name === 'build' || at.task === null || at.task === undefined) return
+  // The worker IS `build`'s work, and so is every group on the way to it:
+  // a `typecheck` behind `build: npm run typecheck` waited for `build`,
+  // and the run refused the cycle (D-16).
+  for (const name of [...seen, at.name]) {
+    const t = byName.get(name)!.task!
+    if (name !== 'build' && Array.isArray(t['dependsOn'])) {
+      t['dependsOn'] = (t['dependsOn'] as string[]).filter((d) => d !== 'build')
+    }
+  }
+  const deps = Array.isArray(at.task['dependsOn']) ? (at.task['dependsOn'] as string[]) : []
+  if (!deps.includes('^build')) at.task['dependsOn'] = ['^build', ...deps]
+  const todo = cacheTodo(String((at.task['exec'] as { command?: unknown }).command))
+  if (!at.todos.includes(todo)) at.todos.push(todo)
+}
+
+/**
+ * A root script that runs the members rather than checking the repo:
+ * pnpm's `-r` / `--filter` / `-C`, Yarn's `--cwd` (excalidraw's
+ * `build:common`) and `yarn workspace <name>` (cal.com's `prisma`), npm's
+ * `--prefix`, the workspace flags, Bun's `--filter`,
+ * Vite+'s `vp run` (tiptap), and the other runners, vx itself included. Mapped, it ran every member's
+ * task again beside the member's own (D-45).
+ */
+const RUNS_MEMBERS =
+  /(^|[\s;&|(])(turbo|nx|lerna|ultra|wireit|nps|moon|rush|vx)(\s|$)|\bworkspaces?\s+(foreach|run)\b|\byarn\s+workspace\s|\bvp\s+run\s/
+
+/** A workspace flag, read only where a package manager takes it (`pmRunsMembers`). */
+const MEMBER_FLAG =
+  /^(-r|--recursive|--filter|-F|--workspaces|-ws|--workspace|-w|-C|--dir|--cwd|--prefix|--if-present|--parallel|--stream)(=|$)/
+
+/**
+ * The workspace flags are a package manager's: on the program it runs they
+ * mean something else, and berry's `bench` (`yarn node -r ./setup.ts …`,
+ * node's `--require`) was left out as running the members (D-81). With no
+ * manager named, `node <bin> run` is one (npm/cli's own npm), and not
+ * `docker run -w` (D-83).
+ */
+function pmRunsMembers(script: string): boolean {
+  for (const segment of script.split(/&&|\|\||[;|()]/)) {
+    const words = segment.trim().split(/\s+/)
+    let i = words.findIndex((w) => /^(pnpm|pn|npm|yarn|bun)$/.test(w))
+    // npm/cli runs itself: `node . run test --workspaces`.
+    if (i < 0) i = words.findIndex((w, j) => w === 'run' && words[j - 2] === 'node')
+    if (i < 0) continue
+    // `exec`, `dlx` and `x` take the manager's flags up to the program name.
+    let program = false
+    for (i++; i < words.length; i++) {
+      const w = words[i]!
+      if (MEMBER_FLAG.test(w)) return true
+      if (program && !w.startsWith('-')) break
+      if (w === 'node') break
+      if (w === 'exec' || w === 'dlx' || w === 'x') program = true
+    }
+  }
+  return false
+}
+
+// A bare target may escape a space or paren (`cd packages/my\ app`).
+const CD = /(?:^|[\s;&|(])cd\s+("[^"]*"|'[^']*'|(?:\\.|[^\s;&|()\\])+)/g
+
+/**
+ * A `cd` into a member's directory, or one holding members, runs that
+ * member's work (kit's `cd packages/kit && vitest run`); bun's
+ * `typecheck` (`cd test && bun run typecheck`) enters no member and was
+ * left out (D-83). A target vx cannot read (`$DIR`, `~`) still counts.
+ */
+function cdsToMembers(script: string, rootDir: string, memberDirs: readonly string[]): boolean {
+  for (const m of script.matchAll(CD)) {
+    const quoted = /^(["'])(.*)\1$/.exec(m[1]!)
+    const target = quoted ? quoted[2]! : m[1]!.replace(/\\(.)/g, '$1')
+    if (/[$`~*?]/.test(target) || target === '-') return true
+    const dir = path.resolve(rootDir, target)
+    const inside = (a: string, b: string): boolean => a === b || a.startsWith(b + path.sep)
+    if (memberDirs.some((d) => inside(d, dir) || inside(dir, d))) return true
+  }
+  return false
+}
+
+/**
+ * The manager a root's files name, or undefined: `pnpm-workspace.yaml` is
+ * pnpm's whatever the lockfile, and the npm `ownerOf` falls back to at the
+ * file-system root with no lockfile anywhere is no claim.
+ */
+function rootManager(dir: string, memo: Map<string, Owner>): string | undefined {
+  if (existsSync(path.join(dir, 'pnpm-workspace.yaml'))) return 'pnpm'
+  const owner = ownerOf(dir, memo)
+  const guessed =
+    owner.at === path.parse(owner.at).root && !existsSync(path.join(owner.at, 'package-lock.json'))
+  return guessed ? undefined : owner.manager
+}
+
+/**
+ * How the repo's own manager runs the members, for the root note: an npm
+ * repo read "(`pnpm -r`, `--filter`, a runner)" (insomnia).
+ */
+function membersExample(manager: string | undefined): string {
+  switch (manager) {
+    case 'npm':
+      return '`--workspaces`, `-w`'
+    case 'yarn':
+      return '`yarn workspaces run`, `yarn workspace`'
+    case 'berry':
+      return '`yarn workspaces foreach`, `yarn workspace`'
+    case 'bun':
+      return '`bun --filter`'
+    default:
+      return '`pnpm -r`, `--filter`'
+  }
+}
+
+/**
+ * The hooks a package's build hides in when it has no `build` script:
+ * react-navigation's twelve packages build in `prepack: bob build`, their
+ * root's `build` (`lerna run prepack`) runs the members and is left out,
+ * and the repo mapped with no build at all.
+ */
+const LIFECYCLE_BUILD_HOOKS = ['prepack', 'prepublishOnly', 'prepublish', 'prepare']
+const BUILDER =
+  /(?:^|[\s;&|(])(?:bob build|tsc|tsup|tsdown|rollup|vite build|babel|unbuild|esbuild|webpack|microbundle|pkgroll|bunchee|preconstruct build)(?:\s|$)/
+
+/** The workspace flags that move a package manager off the package it runs in. */
+const ELSEWHERE_FLAG = /^(-r|--recursive|--filter|-F|--workspaces|-ws|--workspace)(=|$)/
+const DIR_FLAG = /^(-C|--dir|--cwd|--prefix)(?:=(.*))?$/
+
+/**
+ * The part of a member's script that runs another member's work: pinia's
+ * online-playground `build` is `pnpm -C ../pinia run build && vite build`,
+ * and mapped verbatim it built pinia again beside pinia's own task, writing
+ * the dist its siblings read. `yarn workspace <name>`, a runner, `pnpm -r`
+ * / `--filter`, and a `cd` / `-C` / `--cwd` / `--prefix` whose innermost
+ * member is another one count; a fixture inside the member, or the root,
+ * does not.
+ */
+function siblingRun(script: string, dir: string, others: readonly string[]): string | undefined {
+  const inside = (a: string, b: string): boolean => a === b || a.startsWith(b + path.sep)
+  const intoOther = (target: string): boolean => {
+    const t = path.resolve(dir, target.replace(/^(["'])(.*)\1$/, '$2'))
+    if (/[$`~*?]/.test(target)) return false
+    const owner = [dir, ...others]
+      .filter((d) => inside(t, d))
+      .sort((x, y) => y.length - x.length)[0]
+    return owner !== undefined && owner !== dir
+  }
+  for (const segment of script.split(/&&|\|\||[;|()]/)) {
+    const s = segment.trim()
+    if (RUNS_MEMBERS.test(` ${s}`)) return s
+    for (const m of s.matchAll(CD)) if (intoOther(m[1]!)) return s
+    const words = s.split(/\s+/)
+    const at = words.findIndex((w) => /^(pnpm|pn|npm|yarn|bun)$/.test(w))
+    if (at < 0) continue
+    for (let i = at + 1; i < words.length; i++) {
+      const w = words[i]!
+      if (ELSEWHERE_FLAG.test(w)) return s
+      const flag = DIR_FLAG.exec(w)
+      if (flag === null) continue
+      const target = flag[2] ?? words[++i]
+      if (target !== undefined && intoOther(target)) return s
+    }
+  }
+  return undefined
+}
+
+/**
+ * The package globs a `lerna.json` beside a lone root lists (Lerna's
+ * default when it names none), or undefined: Lerna-classic repos list
+ * their packages there, not in `workspaces`, and vx saw the root alone
+ * (D-111).
+ */
+function lernaPackages(dir: string): string[] | undefined {
+  let json: unknown
+  try {
+    json = JSON.parse(readFileSync(path.join(dir, 'lerna.json'), 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return undefined
+  }
+  const listed = (json as { packages?: unknown } | null)?.packages
+  return Array.isArray(listed) && listed.every((g) => typeof g === 'string') && listed.length > 0
+    ? listed
+    : ['packages/*']
+}
+
+function lernaNote(globs: readonly string[]): string {
+  const list = globs.map((g) => JSON.stringify(g)).join(', ')
+  return `lerna.json lists the packages (${list}), but package.json declares no \`workspaces\`, so vx sees the root alone: add \`"workspaces": [${list}]\` to package.json and run \`vx init\` again`
+}
+
+/**
+ * Yarn 2+ installs with Plug'n'Play unless `.yarnrc.yml` names another
+ * linker: a package's bins live in `.pnp.cjs`, and a task's `json5` exited
+ * 127 under vx, which runs no `yarn` in front of a command (probed on Yarn
+ * 4.5).
+ */
+function usesPnp(dir: string): boolean {
+  let rc = ''
+  try {
+    rc = readFileSync(path.join(dir, '.yarnrc.yml'), 'utf8')
+  } catch {}
+  const linker = /^nodeLinker:\s*["']?([\w-]+)/m.exec(rc)?.[1]
+  return linker === undefined || linker === 'pnp'
+}
+
+const PNP_NOTE =
+  "Yarn Plug'n'Play installs this repo: a package's bins live in `.pnp.cjs`, not `node_modules/.bin`, so a task's `tsc` is not found under vx — set `nodeLinker: node-modules` in `.yarnrc.yml` and run `yarn install`, or write each command as `yarn exec '<command>'`"
+
+/** A runner of this package's scripts by name: `run-p build:*`. */
+const RUNS_OWN = /(?:^|\s)(?:run-s|run-p|npm-run-all)(?:\s|$)/
+
+/** A package manager running a script by name: `pnpm build`, `npm run x`, `bun run x`. */
+const RUNS_SCRIPT =
+  /(?:^|[\s;&|(])(?:pnpm|pn|npm|yarn|bun)\s+(?:run(?:-script)?\s+)?([^\s;&|()'"-][^\s;&|()'"]*)/g
+
+/**
+ * The scripts a command runs by name: a package manager's (`pnpm x`, `npm
+ * run x`), `run-s` / `run-p` / `npm-run-all` (`build:*` is one segment,
+ * `build:**` any), and `concurrently "npm:x"`. A root `ci: run-s build:all
+ * lint` over `build:all: pnpm -r build` mapped as a root task (D-95).
+ */
+function scriptRefs(command: string, scripts: readonly (readonly [string, string])[]): string[] {
+  const refs = [...command.matchAll(RUNS_SCRIPT)].map((m) => m[1]!)
+  for (const m of command.matchAll(/["']?\b(?:npm|pnpm|yarn|bun):([^\s"']+)/g)) refs.push(m[1]!)
+  for (const segment of command.split(/&&|\|\||[;|()]/)) {
+    const words = segment.trim().split(/\s+/)
+    const at = words.findIndex((w) => /^(run-s|run-p|npm-run-all)$/.test(w))
+    if (at < 0) continue
+    for (const w of words.slice(at + 1)) {
+      if (w.startsWith('-')) continue
+      const name = w.replace(/^(["'])(.*)\1$/, '$2')
+      if (!name.includes('*')) {
+        refs.push(name)
+        continue
+      }
+      const re = new RegExp(
+        `^${name
+          .split(/(\*\*|\*)/)
+          .map((part) =>
+            part === '**'
+              ? '.*'
+              : part === '*'
+                ? '[^:]*'
+                : part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'),
+          )
+          .join('')}$`,
+      )
+      for (const [n] of scripts) if (re.test(n)) refs.push(n)
+    }
+  }
+  return refs
+}
+
+/**
+ * The scripts that run the members, directly or through another of these
+ * scripts: vite's `ci-docs` (`pnpm build && pnpm docs-build`) runs each
+ * member's build through the root's own `build` (`pnpm -r … run build`).
+ */
+function runningMembers(
+  scripts: Readonly<Record<string, unknown>>,
+  rootDir: string,
+  memberDirs: readonly string[],
+): Set<string> {
+  const text = Object.entries(scripts).filter(
+    (e): e is [string, string] => typeof e[1] === 'string',
+  )
+  const out = new Set(
+    text
+      .filter(
+        ([, v]) =>
+          RUNS_MEMBERS.test(` ${v}`) || pmRunsMembers(v) || cdsToMembers(v, rootDir, memberDirs),
+      )
+      .map(([n]) => n),
+  )
+  for (let grew = true; grew;) {
+    grew = false
+    for (const [n, v] of text) {
+      if (out.has(n)) continue
+      if (scriptRefs(v, text).some((r) => out.has(r))) {
+        out.add(n)
+        grew = true
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * `outside`: the root manifest when the root is no member (pnpm's and
+ * Yarn's default), whose own scripts (`lint: eslint .`) went unmapped
+ * without a word; `outsideDir` is where it sits.
+ */
+export function migrateScripts(
+  metas: readonly PackageMeta[],
+  outside?: Readonly<Record<string, unknown>>,
+  outsideDir?: string,
+): MigrationPlan {
+  const projects: GeneratedProject[] = []
+  const hookMemo = new Map<string, Owner>()
+  // The workspace root among members: many of its scripts run the
+  // workspace (`npm run build --workspaces`, `pnpm -r build`), and a root
+  // task made of one ran every member's build again under `--all`. Since
+  // D-39 a hand-written root config makes the root a project, and
+  // `--force` replaced it so (D-45). A lone package is its repo's project
+  // and maps.
+  const root = metas.length > 1 ? workspaceRootOf(metas) : undefined
+  const notes: string[] = []
+  const lifecycleBuilds: [string, string, string][] = []
+  // The rest check the whole repo (`lint: oxlint .`, `test: vitest`):
+  // `vx run lint` found no project in remix, wagmi or element-plus. Such a
+  // script maps onto the root, when the root has a name (vx skips a
+  // nameless one's config), no config of its own, and no member declares
+  // the task, so `--all` never runs one check twice.
+  const outsideName =
+    typeof outside?.['name'] === 'string' && outside['name'] !== '' ? outside['name'] : undefined
+  // insomnia's root is named as its `packages/insomnia`: a root config made
+  // it a project, and every later run was refused for the duplicate (D-129).
+  const clash = outsideName === undefined ? undefined : metas.find((m) => m.name === outsideName)
+  // A root with a config of its own is kept as written, and a run of `vx
+  // init` after the one that mapped it keeps it like a member's (X-27).
+  const rootKept = root !== undefined && root.configPath !== null
+  const rootMeta: PackageMeta | undefined =
+    root !== undefined
+      ? rootKept
+        ? undefined
+        : root
+      : outsideName !== undefined && outsideDir !== undefined && clash === undefined
+        ? { name: outsideName, dir: outsideDir, packageJson: outside as never, configPath: null }
+        : undefined
+  const memberTasks = new Set(
+    metas
+      .filter((m) => m !== root)
+      .flatMap((m) => Object.entries(scriptsOf(m)))
+      .filter(([, v]) => typeof v === 'string' && v !== '')
+      .map(([n]) => n),
+  )
+  // The root scripts left out, by why: jest's root `build` (every package's)
+  // went unnamed beside the website's, and `vx run build --all` built the
+  // website alone (D-85). A left-out script's `pre` / `post` hook goes with
+  // it where the manager runs hooks: kept, it became a task of its own.
+  const leftOut = (meta: PackageMeta): { runs: string[]; shared: string[]; out: Set<string> } => {
+    const scripts = scriptsOf(meta)
+    const runs = runningMembers(
+      scripts,
+      meta.dir,
+      metas.filter((m) => m !== root).map((m) => m.dir),
+    )
+    const hooks = runsScriptHooks(meta.dir, hookMemo) !== null
+    const hookOf = (n: string): string | undefined => {
+      const base = hooks ? /^(?:pre|post)(.+)$/.exec(n)?.[1] : undefined
+      return base !== undefined && typeof scripts[base] === 'string' ? base : undefined
+    }
+    // A hook rides in its script's command, so it is judged with it.
+    const named = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && !LIFECYCLE.test(n) && hookOf(n) === undefined,
+    )
+    const left = {
+      runs: named.filter((n) => runs.has(n)),
+      shared: named.filter((n) => memberTasks.has(n) && !runs.has(n)),
+    }
+    const outNames = new Set([...left.runs, ...left.shared])
+    const out = new Set(
+      Object.keys(scripts).filter((n) => outNames.has(n) || outNames.has(hookOf(n) ?? '')),
+    )
+    return { ...left, out }
+  }
+  const rootScripts = (meta: PackageMeta): Record<string, unknown> => {
+    const scripts = scriptsOf(meta)
+    const { out } = leftOut(meta)
+    return Object.fromEntries(
+      Object.entries(scripts).filter(([n, v]) => typeof v === 'string' && !out.has(n)),
+    )
+  }
+  const mapsOf = (meta: PackageMeta | undefined): number =>
+    meta === undefined ? 0 : Object.keys(rootScripts(meta)).filter((n) => !LIFECYCLE.test(n)).length
+  const rootMapped = mapsOf(rootMeta)
+  const listed = (names: readonly string[]): string =>
+    names.slice(0, 8).join(', ') + (names.length > 8 ? ` and ${names.length - 8} more` : '')
+  const outsideScripts = outside?.['scripts']
+  const outsideRuns =
+    typeof outsideScripts === 'object' &&
+    outsideScripts !== null &&
+    Object.values(outsideScripts).some((v) => typeof v === 'string' && v !== '')
+  const unnamedMaps = (): string[] => {
+    const meta: PackageMeta = {
+      name: 'package.json',
+      dir: outsideDir!,
+      packageJson: outside as never,
+      configPath: null,
+    }
+    const scripts = scriptsOf(meta)
+    return Object.keys(rootScripts(meta)).filter((n) => {
+      // A hook rides in its script's command and is no script to name.
+      const base = /^(?:pre|post)(.+)$/.exec(n)?.[1]
+      return !LIFECYCLE.test(n) && (base === undefined || !(base in scripts))
+    })
+  }
+  // Why a root mapped nothing: `eslint .` beside a member's `lint` runs
+  // nothing of the workspace, and the note said it did.
+  const rootLeftOut = (): string => {
+    const judged = rootKept ? root : rootMeta
+    if (judged === undefined) return 'run the workspace'
+    const scripts = scriptsOf(judged)
+    const named = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '' && !LIFECYCLE.test(n),
+    )
+    const runs = runningMembers(
+      scripts,
+      judged.dir,
+      metas.filter((m) => m !== root).map((m) => m.dir),
+    )
+    const shared = named.filter((n) => memberTasks.has(n) && !runs.has(n))
+    if (shared.length === 0) return 'run the workspace'
+    const list = `${shared.slice(0, 8).join(', ')}${shared.length > 8 ? ', …' : ''}`
+    return `${shared.length < named.length ? 'run the workspace or ' : ''}share a member's task name (${list})`
+  }
+  const rootName =
+    root?.name ??
+    (outsideRuns
+      ? typeof outside?.['name'] === 'string' && outside['name'] !== ''
+        ? outside['name']
+        : 'package.json'
+      : undefined)
+  if (rootName !== undefined && rootMapped > 0) {
+    const { runs, shared } = leftOut(rootMeta!)
+    notes.push(
+      `${rootName} (the workspace root): its scripts that check the whole repo are its tasks` +
+        (runs.length > 0
+          ? `; left out as running the members (${membersExample(rootMeta && rootManager(rootMeta.dir, hookMemo))}, a runner): ${listed(runs)}`
+          : '') +
+        (shared.length > 0
+          ? `; left out as a member's task name, so \`--all\` never runs one twice: ${listed(shared)} — one that does other work maps by hand under a name of its own`
+          : ''),
+    )
+  } else if (clash !== undefined && outsideDir !== undefined && unnamedMaps().length > 0) {
+    const would = unnamedMaps()
+    notes.push(
+      `${clash.name} (the workspace root) not mapped: ${relPosix(outsideDir, clash.dir)} has the same "name", and vx names a project by it; rename the root's and run \`vx init\` again to map ${would.length} of its scripts (${would.slice(0, 8).join(', ')}${would.length > 8 ? ', …' : ''})`,
+    )
+  } else if (rootName === 'package.json' && outsideDir !== undefined && unnamedMaps().length > 0) {
+    // react's nameless root: "its scripts run the workspace" was not why,
+    // and 30 of its scripts (`build`, `lint`, `test`) map once it has a
+    // name (D-87).
+    const would = unnamedMaps()
+    notes.push(
+      `package.json (the workspace root) not mapped: it has no "name", and vx names a project by it; give it one and run \`vx init\` again to map ${would.length} of its scripts (${would.slice(0, 8).join(', ')}${would.length > 8 ? ', …' : ''})`,
+    )
+  } else if (rootName !== undefined && !(rootKept && mapsOf(root) > 0)) {
+    // A nameless root's vx.config is skipped (vx names projects by their
+    // manifest's name), so the hand-written one needs a name first (vuejs/core).
+    notes.push(
+      `${rootName} (the workspace root) not mapped: its scripts ${rootLeftOut()}; declare its own tasks in its vx.config by hand` +
+        (rootName === 'package.json' ? ', after giving its package.json a "name"' : ''),
+    )
+  }
+  const mapped = metas.filter((m) => m !== root)
+  if (rootMeta !== undefined && rootMapped > 0) mapped.push(rootMeta)
+  for (const meta of mapped) {
+    const scripts = meta === rootMeta ? rootScripts(meta) : scriptsOf(meta)
+    const hooksBy = runsScriptHooks(meta.dir, hookMemo)
+    const runsHooks = hooksBy !== null
+    const berry = ownerOf(meta.dir, hookMemo).manager === 'berry'
+    const runnable = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '',
+    )
+    // A script whose name no task may carry (`lint#fix`, `^up`) was written
+    // as one, and the next run refused the whole config (item 1033). It is
+    // left out, with a TODO, and a script delegating to it keeps its
+    // command rather than naming it as an edge.
+    const refused = runnable.flatMap((n) => {
+      const why = taskNameProblem(n)
+      return why === null ? [] : [[n, why] as const]
+    })
+    const names = runnable.filter((n) => taskNameProblem(n) === null)
+    if (meta !== rootMeta && !('build' in scripts)) {
+      const hook = LIFECYCLE_BUILD_HOOKS.find(
+        (h) => typeof scripts[h] === 'string' && BUILDER.test(scripts[h]),
+      )
+      if (hook !== undefined) lifecycleBuilds.push([meta.name, hook, scripts[hook] as string])
+    }
+    if (runnable.length === 0) continue
+    const hasBuild = names.includes('build')
+    const has = (n: string): boolean => names.includes(n)
+    // Lifecycle hooks are npm's, not tasks anyone runs by name, and a hook
+    // of a script that exists rides inside that script's command.
+    const isTask = (n: string): boolean => {
+      if (!has(n) || LIFECYCLE.test(n)) return false
+      const hookOf = runsHooks ? /^(pre|post)(.+)$/.exec(n) : null
+      return hookOf === null || !has(hookOf[2]!) || LIFECYCLE.test(hookOf[2]!)
+    }
+    const tasks: GeneratedTask[] = []
+    let readsManifest = false
+    const text = Object.entries(scripts).filter(
+      (e): e is [string, string] => typeof e[1] === 'string',
+    )
+    for (const name of names) {
+      if (!isTask(name)) continue
+
+      const todos: string[] = []
+      const own = berry ? berryRun(scripts[name] as string) : (scripts[name] as string)
+      const delegate = delegatedScript(own)
+      // npm lifecycle hooks (`prepack`, `prepublishOnly`, …) belong to the
+      // package manager and never ride inside a task — `pack` stays alone.
+      const hook = (h: string): boolean => runsHooks && has(h) && !LIFECYCLE.test(h)
+      const hooks = [`pre${name}`, `post${name}`].filter(hook)
+      // A group over a script that is no task (`setup: npm run prepare`)
+      // named a task nothing defines, and the run `vx init` suggested
+      // refused the config (D-12).
+      if (delegate !== null && isTask(delegate) && delegate !== name && hooks.length === 0) {
+        // A group: no exec, the graph runs the target. `npm test` calling
+        // `vitest` through `npm run test:unit` is two tasks, not a subprocess.
+        const task: Record<string, unknown> = { dependsOn: [delegate] }
+        if (AFTER_BUILD.has(name) && hasBuild && delegate !== 'build') {
+          task['dependsOn'] = [delegate, 'build']
+        }
+        tasks.push({ name, todos, task })
+        continue
+      }
+
+      const command = foldScriptHooks(
+        hook(`pre${name}`) ? (scripts[`pre${name}`] as string) : undefined,
+        own,
+        hook(`post${name}`) ? (scripts[`post${name}`] as string) : undefined,
+      )
+      if (hooks.length > 0) {
+        todos.push(
+          `${hooksBy} ran ${hooks.map((h) => `\`${h}\``).join(' and ')} around this script without being asked; folded into the command in that order`,
+        )
+      }
+      const sibling =
+        meta === rootMeta
+          ? undefined
+          : siblingRun(
+              own,
+              meta.dir,
+              metas.filter((m) => m !== root && m !== meta).map((m) => m.dir),
+            )
+      if (sibling !== undefined) {
+        todos.push(
+          `\`${sibling}\` runs another member's work outside the graph, again beside that member's own task: name that task under dependsOn (\`<member>#<task>\`) and drop it from the command`,
+        )
+      }
+      // A chain of this package's own scripts (`check: pnpm run build &&
+      // pnpm run lint`) ran each again inside the command, beside the task
+      // of that name: `vx run check` built twice. The chain's order may
+      // matter, so it is named rather than turned into a group.
+      // Through `run-s` / `run-p` / `npm-run-all` too (`build: run-p
+      // build:*`), each segment naming every task it runs (M-48). A
+      // persistent one has PERSISTENT_TODO.
+      const persistent = isPersistent(name, scripts)
+      let ranTasks = 0
+      const ownRuns = own
+        .split(/&&|\|\||;/)
+        .map((part) => part.trim())
+        .filter((part) => {
+          const d = delegatedScript(part)
+          if (d !== null) {
+            if (d === name || !isTask(d)) return false
+            ranTasks++
+            return true
+          }
+          if (persistent || !RUNS_OWN.test(part)) return false
+          const refs = new Set(scriptRefs(part, text).filter((r) => r !== name && isTask(r)))
+          ranTasks += refs.size
+          return refs.size > 0
+        })
+      if (ownRuns.length > 0) {
+        const list = ownRuns.map((r) => `\`${r}\``).join(', ')
+        todos.push(
+          `${list} ${ownRuns.length === 1 ? 'runs' : 'run'} this package's own ${
+            ranTasks === 1
+              ? 'task again inside the command, beside that task: name it'
+              : 'tasks again inside the command, beside those tasks: name them'
+          } under dependsOn and drop ${ownRuns.length === 1 ? 'it' : 'them'} from the command`,
+        )
+      }
+      const exec: Record<string, unknown> = { command }
+      const npm = npmEnv(command, name, hooks.length > 0)
+      if (Object.keys(npm.define).length > 0) exec['env'] = { define: npm.define }
+      if (npm.readsManifest) readsManifest = true
+      for (const v of npm.unset) {
+        todos.push(
+          `the script reads $${v}, which the package manager sets and vx does not: define it under exec.env.define or drop it`,
+        )
+      }
+      const task: Record<string, unknown> = { exec }
+      if (persistent) {
+        exec['persistent'] = {}
+        todos.push(PERSISTENT_TODO)
+      }
+      if (name === 'build') {
+        task['dependsOn'] = ['^build']
+        todos.push(cacheTodo(own))
+      } else if (AFTER_BUILD.has(name) && hasBuild) {
+        task['dependsOn'] = ['build']
+      }
+      tasks.push({ name, todos, task })
+    }
+    for (const [name, why] of refused) {
+      tasks.push({
+        name,
+        todos: [
+          `script ${JSON.stringify(name)} not migrated: its name ${why} — rename the script, or add it by hand under another name`,
+        ],
+        task: null,
+      })
+    }
+    upstreamBuildOnWorker(tasks)
+    if (tasks.length > 0) {
+      const importLines = readsManifest ? [MANIFEST_IMPORT] : []
+      projects.push({ name: meta.name, dir: meta.dir, importLines, tasks })
+    }
+  }
+  const owner = metas[0] === undefined ? undefined : ownerOf(metas[0].dir, hookMemo)
+  if (owner?.manager === 'berry' && usesPnp(owner.at)) notes.push(PNP_NOTE)
+
+  if (lifecycleBuilds.length > 0) {
+    const [name, hook, command] = lifecycleBuilds[0]!
+    const more = lifecycleBuilds.length - 1
+    notes.push(
+      `${lifecycleBuilds.length === 1 ? 'a package builds' : `${lifecycleBuilds.length} packages build`} only in a lifecycle script (\`${hook}: ${command}\` in ${name}${more > 0 ? ` and ${more} more` : ''}), which the package manager runs on pack or install and vx never runs: add a \`build\` script running it and run \`vx init\` again`,
+    )
+  }
+  const lerna = metas.length === 1 ? lernaPackages(metas[0]!.dir) : undefined
+  if (lerna !== undefined) notes.push(lernaNote(lerna))
+  rootBinBuilds(projects, metas, root?.packageJson ?? outside)
+  breakBuildCycles(projects, metas)
+  pruneOrphanPersistentNotes(projects, PERSISTENT_TODO)
+  return {
+    headerNotes: [
+      // Where to add one is the TODO's to say, when there is one: an Nx repo
+      // whose only script is `codegen` read "`build` carries a TODO" over
+      // "0 TODOs" (the first-five-minutes walk, 2026-09-28).
+      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so no task got a cache block',
+    ],
+    projects,
+    extraFiles: [],
+    notes,
+  }
+}
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
+
+const depsOf = (manifest: object | undefined): Set<string> =>
+  new Set(
+    DEP_FIELDS.flatMap((f) => {
+      const deps = (manifest as Record<string, unknown> | undefined)?.[f]
+      return typeof deps === 'object' && deps !== null ? Object.keys(deps) : []
+    }),
+  )
+
+/** The bin names a manifest declares: `bin: './cli.js'` is named after the package. */
+function binsOf(manifest: object, name: string): string[] {
+  const bin = (manifest as Record<string, unknown>)['bin']
+  if (typeof bin === 'string') return [name.replace(/^@[^/]+\//, '')]
+  return typeof bin === 'object' && bin !== null ? Object.keys(bin) : []
+}
+
+/**
+ * A member's script that runs a workspace package's bin it gets only
+ * through the root's dependencies (vite's playgrounds run `vite` from the
+ * root's `vite: workspace:*`) has no `^build` edge to that package: 64 of
+ * 70 playground builds ran before vite's own (Growth's trial 4, F9). Each
+ * such task waits on that package's build too.
+ */
+function rootBinBuilds(
+  projects: GeneratedProject[],
+  metas: readonly PackageMeta[],
+  rootManifest: object | undefined,
+): void {
+  const fromRoot = depsOf(rootManifest)
+  if (fromRoot.size === 0) return
+  const builds = new Set(
+    projects
+      .filter((p) => p.tasks.some((t) => t.name === 'build' && t.task !== null))
+      .map((p) => p.name),
+  )
+  const owner = new Map<string, string>()
+  for (const m of metas)
+    if (fromRoot.has(m.name) && builds.has(m.name))
+      for (const b of binsOf(m.packageJson, m.name)) owner.set(b, m.name)
+  if (owner.size === 0) return
+  const metaOf = new Map(metas.map((m) => [m.name, m]))
+  for (const p of projects) {
+    const own = depsOf(metaOf.get(p.name)?.packageJson)
+    for (const t of p.tasks) {
+      const command = (t.task?.['exec'] as { command?: unknown } | undefined)?.command
+      if (typeof command !== 'string') continue
+      const needs = new Set(
+        command
+          .split(/[\s;&|()]+/)
+          .map((w) => owner.get(w))
+          .filter((n): n is string => n !== undefined && n !== p.name && !own.has(n)),
+      )
+      if (needs.size === 0) continue
+      const deps = Array.isArray(t.task!['dependsOn']) ? (t.task!['dependsOn'] as string[]) : []
+      t.task!['dependsOn'] = [...deps, ...[...needs].sort().map((n) => `${n}#build`)]
+    }
+  }
+}
+
+/**
+ * pnpm sorts a dependency cycle away and builds anyway; vx's `^build`
+ * refuses it, so the config init wrote failed its first run (nuxt:
+ * `@nuxt/nitro-server` devDepends on `nuxt`, which depends on it; vitest's
+ * browser packages). A package in a cycle of builds waits, instead of on
+ * `^build`, on each build outside its cycle that `^build` reaches (through
+ * packages with none, as core walks it), with a TODO to order the cycle.
+ */
+function breakBuildCycles(projects: GeneratedProject[], metas: readonly PackageMeta[]): void {
+  const builds = new Set(
+    projects
+      .filter((p) => p.tasks.some((t) => t.name === 'build' && t.task !== null))
+      .map((p) => p.name),
+  )
+  if (builds.size < 2) return
+  // The edges the lockfile plugin init declares will give `^build`: the
+  // manager installs what a manifest names, so a key naming a workspace
+  // package is one. Core's graph reads no manifest; this mapper reads
+  // package.json throughout.
+  const names = new Set(metas.map((m) => m.name))
+  const direct = new Map<string, string[]>()
+  for (const m of metas) {
+    const own = new Set<string>()
+    for (const field of [
+      m.packageJson.dependencies,
+      m.packageJson.devDependencies,
+      m.packageJson.optionalDependencies,
+    ]) {
+      if (field === null || typeof field !== 'object') continue
+      for (const key of Object.keys(field)) if (key !== m.name && names.has(key)) own.add(key)
+    }
+    direct.set(m.name, [...own])
+  }
+  const directDeps = (name: string): readonly string[] => direct.get(name) ?? []
+  const holders = new Map<string, string[]>()
+  for (const name of builds) {
+    const found = new Set<string>()
+    const visited = new Set([name])
+    const frontier = [...directDeps(name)]
+    while (frontier.length > 0) {
+      const at = frontier.pop()!
+      if (visited.has(at)) continue
+      visited.add(at)
+      if (builds.has(at)) found.add(at)
+      else frontier.push(...directDeps(at))
+    }
+    holders.set(name, [...found].sort())
+  }
+  for (const cycle of cyclesOf(holders)) {
+    const members = new Set(cycle)
+    for (const p of projects) {
+      if (!members.has(p.name)) continue
+      const at = p.tasks.find(
+        (t) =>
+          Array.isArray(t.task?.['dependsOn']) &&
+          (t.task['dependsOn'] as string[]).includes('^build'),
+      )
+      if (at === undefined) continue
+      const outside = holders
+        .get(p.name)!
+        .filter((h) => !members.has(h))
+        .map((h) => `${h}#build`)
+      at.task!['dependsOn'] = (at.task!['dependsOn'] as string[]).flatMap((d) =>
+        d === '^build' ? outside : [d],
+      )
+      at.todos.push(
+        `its package is in a dependency cycle (${cycle.join(', ')}), where \`^build\` would refuse the run — it waits on the builds outside the cycle; order the ones inside it by hand`,
+      )
+    }
+  }
+}
+
+/** The strongly connected components of more than one node (Tarjan), each sorted. */
+function cyclesOf(edges: ReadonlyMap<string, readonly string[]>): string[][] {
+  const index = new Map<string, number>()
+  const low = new Map<string, number>()
+  const stack: string[] = []
+  const onStack = new Set<string>()
+  const out: string[][] = []
+  const visit = (v: string): void => {
+    index.set(v, index.size)
+    low.set(v, index.get(v)!)
+    stack.push(v)
+    onStack.add(v)
+    for (const w of edges.get(v) ?? []) {
+      if (!index.has(w)) {
+        visit(w)
+        low.set(v, Math.min(low.get(v)!, low.get(w)!))
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v)!, index.get(w)!))
+      }
+    }
+    if (low.get(v) === index.get(v)) {
+      const comp: string[] = []
+      let w: string
+      do {
+        w = stack.pop()!
+        onStack.delete(w)
+        comp.push(w)
+      } while (w !== v)
+      if (comp.length > 1) out.push(comp.sort())
+    }
+  }
+  for (const v of [...edges.keys()].sort()) if (!index.has(v)) visit(v)
+  return out
+}
+
+/** The member whose directory holds every other member's, if one does. */
+function workspaceRootOf(metas: readonly PackageMeta[]): PackageMeta | undefined {
+  const outer = metas.reduce((a, b) => (b.dir.length < a.dir.length ? b : a))
+  const prefix = outer.dir.endsWith(path.sep) ? outer.dir : outer.dir + path.sep
+  return metas.every((m) => m === outer || m.dir.startsWith(prefix)) ? outer : undefined
+}