@vzn/vx 0.0.18 → 0.0.22

package/src/workspace/migrate-scripts.ts

@@ -0,0 +1,187 @@
+// 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.
+
+import type { ProjectMeta } from './workspace.js'
+import {
+  foldScriptHooks,
+  type GeneratedProject,
+  type GeneratedTask,
+  type MigrationPlan,
+  PERSISTENT_TASK_NAMES,
+  PERSISTENT_TODO,
+} from './migration.js'
+
+// `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|yarn|bun)(?: (run))?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+      command.trim(),
+    )
+  if (m === null) return null
+  if (m[4] !== undefined) return m[4]
+  const [, manager, run, name] = m
+  // 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. */
+const OWN_COMMANDS: Readonly<Record<string, ReadonlySet<string>>> = {
+  // `bun --help`, Bun 1.4.2, with the short aliases.
+  bun: new Set(
+    'run test x repl exec install i add a remove rm update audit outdated link unlink publish patch pm info why build init create c upgrade feedback lint'.split(
+      ' ',
+    ),
+  ),
+  pnpm: new Set(
+    'add install i update up remove rm link unlink import rebuild prune fetch patch audit list ls outdated why exec dlx create init publish pack store env setup config root bin licenses deploy doctor'.split(
+      ' ',
+    ),
+  ),
+  yarn: new Set(
+    'add install remove upgrade up info init link unlink pack publish why workspace workspaces config cache dlx exec bin node plugin set version constraints npm patch explain dedupe'.split(
+      ' ',
+    ),
+  ),
+}
+
+function scriptsOf(meta: ProjectMeta): 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.
+ */
+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
+  const deps = Array.isArray(at.task['dependsOn']) ? (at.task['dependsOn'] as string[]) : []
+  if (!deps.includes('^build')) at.task['dependsOn'] = ['^build', ...deps]
+}
+
+export function migrateScripts(metas: readonly ProjectMeta[]): MigrationPlan {
+  const projects: GeneratedProject[] = []
+  for (const meta of metas) {
+    const scripts = scriptsOf(meta)
+    const names = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '',
+    )
+    if (names.length === 0) continue
+    const hasBuild = names.includes('build')
+    const has = (n: string): boolean => names.includes(n)
+    const tasks: GeneratedTask[] = []
+    for (const name of names) {
+      // Lifecycle hooks are npm's, not tasks anyone runs by name.
+      if (LIFECYCLE.test(name)) continue
+      // A hook of a script that exists rides inside that script's command.
+      const hookOf = /^(pre|post)(.+)$/.exec(name)
+      if (hookOf !== null && has(hookOf[2]!) && !LIFECYCLE.test(hookOf[2]!)) continue
+
+      const todos: string[] = []
+      const own = 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 => has(h) && !LIFECYCLE.test(h)
+      const hooks = [`pre${name}`, `post${name}`].filter(hook)
+      if (delegate !== null && has(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(
+          `npm ran ${hooks.map((h) => `\`${h}\``).join(' and ')} around this script without being asked; folded into the command in that order`,
+        )
+      }
+      const task: Record<string, unknown> = { exec: { command } }
+      if (PERSISTENT_TASK_NAMES.has(name)) {
+        task['exec'] = { command, persistent: {} }
+        todos.push(PERSISTENT_TODO)
+      }
+      if (name === 'build') {
+        task['dependsOn'] = ['^build']
+        todos.push(
+          "cache: add `cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } }` 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",
+        )
+      } else if (AFTER_BUILD.has(name) && hasBuild) {
+        task['dependsOn'] = ['build']
+      }
+      tasks.push({ name, todos, task })
+    }
+    upstreamBuildOnWorker(tasks)
+    if (tasks.length > 0) projects.push({ name: meta.name, dir: meta.dir, importLines: [], tasks })
+  }
+  return {
+    headerNotes: [
+      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so no task got a cache block — `build` carries a TODO showing the one to add',
+    ],
+    projects,
+    extraFiles: [],
+    notes: [],
+  }
+}

package/src/workspace/migration.ts

@@ -0,0 +1,353 @@
+// The migration seam: what any adoption tool needs once it has a plan —
+// the plan's shape, TS emission, the overwrite guard, the writes and the
+// report. `vx init` (package.json scripts, in core) and `@vzn/vx-migrate`
+// (Turbo, Nx) share it, so a generated config reads the same whichever
+// tool wrote it. Core knows no source format here: a mapper returns a
+// `MigrationPlan` and this file does the rest.
+
+import path from 'node:path'
+import { relPosix, UserError } from '../util/index.js'
+import type { ProjectMeta } from './workspace.js'
+import { loadWorkspace, unreachedHint, unreachedPackages } from './workspace.js'
+
+/**
+ * Escape an arbitrary string into a single-quoted TS literal. Escapes
+ * backslash + quote AND raw newlines/CR — a value with an embedded newline
+ * (legal JSON, e.g. a script `"echo a\necho b"`, or a glob with a `'`) would
+ * otherwise splice into a single-quoted literal as an unterminated / malformed
+ * string that fails to load (generated files must round-trip through the
+ * loader).
+ */
+export function quoteTsLiteral(s: string): string {
+  return `'${s
+    .replaceAll('\\', '\\\\')
+    .replaceAll("'", "\\'")
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')}'`
+}
+
+/**
+ * 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.
+ */
+export const PERSISTENT_TASK_NAMES: ReadonlySet<string> = new Set([
+  'dev',
+  'start',
+  'serve',
+  'watch',
+  'preview',
+])
+
+/**
+ * A package.json script with the `pre<name>` / `post<name>` hooks npm runs
+ * around it, as ONE sh command. Each part runs in its own subshell, so a
+ * `;` or an `exit` in one ends that part alone, and the chain stops at the
+ * first that fails, as npm stops. The parts sit in a function the
+ * forwarded `--` args are appended to, and only the body takes them, as
+ * npm appends them to the script and never to its hooks. A plain ` && `
+ * join handed them to the post hook, and `test -f x && echo A; echo B` ran
+ * `echo B` after a failed pre hook and went green (item 905). Each part
+ * ends on its own line, so a trailing `# comment` cannot swallow the
+ * paren. A script with no hooks is its body, verbatim.
+ */
+export function foldScriptHooks(
+  pre: string | undefined,
+  body: string,
+  post: string | undefined,
+): string {
+  if (pre === undefined && post === undefined) return body
+  const parts = [
+    ...(pre === undefined ? [] : [`(${pre}\n)`]),
+    `(${body} "$@"\n)`,
+    ...(post === undefined ? [] : [`(${post}\n)`]),
+  ]
+  return `vx_script() {\n${parts.join(' && ')}\n}\nvx_script`
+}
+
+/** The one wording every mapper emits for a task it made persistent. */
+export const PERSISTENT_TODO =
+  'persistent task — set persistent.readyWhen (regex matched against output) so ' +
+  'dependents unblock on readiness, and consider exec.timeout to bound the wait'
+
+/** Verbatim TS expression spliced into a generated array (preset spreads). */
+export interface RawExpr {
+  readonly raw: string
+}
+
+export interface GeneratedTask {
+  name: string
+  /** Rendered as `// TODO(vx-migrate): …` above the task + listed in the report. */
+  todos: string[]
+  /** TaskConfig-shaped object; arrays may contain RawExpr splices.
+   *  null = target has no vx representation (skipped; todos explain). */
+  task: Record<string, unknown> | null
+}
+
+export interface GeneratedProject {
+  /** package.json name */
+  name: string
+  /** absolute project dir */
+  dir: string
+  importLines: string[]
+  tasks: GeneratedTask[]
+}
+
+export interface MigrationPlan {
+  /** report lines printed right under the source line */
+  headerNotes: string[]
+  projects: GeneratedProject[]
+  /** extra root-relative files (e.g. the preset) */
+  extraFiles: { relPath: string; contents: string }[]
+  /** trailing report lines (e.g. implicit Nx deps) */
+  notes: string[]
+}
+
+export interface ApplyMigrationArgs {
+  root: string
+  metas: readonly ProjectMeta[]
+  plan: MigrationPlan
+  /** Named in the report and the generated header, e.g. `turbo.json`. */
+  source: string
+  /** The command the user typed, e.g. `vx init` — named in the report. */
+  verb: string
+  dry: boolean
+  force: boolean
+  /**
+   * `vx init` on a workspace with no scripts still has a job (the workspace
+   * file, and a worked example); a migration with nothing to convert is an
+   * error. Default false.
+   */
+  init?: boolean
+  /** Report lines printed under the source line (e.g. "turbo.json found and not read"). */
+  notes?: readonly string[]
+  /**
+   * `ts` (default) writes `vx.config.ts` with the type-only import and
+   * `satisfies`; `mjs` writes `vx.config.mjs` — the same object, untyped —
+   * for a package whose own `tsc --build` includes every `.ts` under it
+   * and compiled the config into its dist (TanStack/query, 2026-09-11).
+   */
+  format?: MigrationFormat
+}
+
+export type MigrationFormat = 'ts' | 'mjs'
+
+/**
+ * Render a plan to files, refuse to overwrite without `force`, write (or
+ * print, under `dry`), and report. Returns the process exit code.
+ */
+export async function applyMigration(args: ApplyMigrationArgs): Promise<number> {
+  const { root, metas, plan, source, verb, dry, force } = args
+  const init = args.init === true
+  const format: MigrationFormat = args.format ?? 'ts'
+  const configName = `vx.config.${format}`
+  const workspaceName = `vx.workspace.${format}`
+  const empty = plan.projects.length === 0
+  if (empty && !init) {
+    throw new UserError(
+      `nothing to migrate: no ${source === 'package.json scripts' ? 'package.json scripts in any workspace member' : 'tasks in ' + source}`,
+    )
+  }
+
+  const files: { relPath: string; abs: string; contents: string }[] = []
+  for (const p of plan.projects) {
+    if (p.tasks.length === 0) continue
+    const abs = path.join(p.dir, configName)
+    files.push({
+      relPath: relPosix(root, abs),
+      abs,
+      contents: renderConfigFile(source, p, verb, format),
+    })
+  }
+  for (const f of plan.extraFiles) {
+    files.push({ relPath: f.relPath, abs: path.join(root, f.relPath), contents: f.contents })
+  }
+  // A migrated workspace must declare its executor and cache — nothing is
+  // applied by default. Emit the workspace file unless the repo already has
+  // one in any supported extension.
+  const hasWorkspaceFile = (
+    await Promise.all(
+      ['vx.workspace.ts', 'vx.workspace.mjs', 'vx.workspace.js'].map((n) =>
+        Bun.file(path.join(root, n)).exists(),
+      ),
+    )
+  ).some(Boolean)
+  if (!hasWorkspaceFile) {
+    const abs = path.join(root, workspaceName)
+    files.push({ relPath: relPosix(root, abs), abs, contents: workspaceFile(format) })
+  }
+
+  if (!dry && !force) {
+    const conflicts = new Set<string>()
+    // A discovered project with ANY existing vx config (.ts/.mjs/.js) — refuse
+    // so we never shadow a hand-written config with a fresh .ts.
+    for (const p of plan.projects) {
+      if (p.tasks.length === 0) continue
+      const meta = metas.find((m) => m.dir === p.dir)
+      if (meta?.configPath) conflicts.add(relPosix(root, meta.configPath))
+    }
+    // ALSO stat every actual write target. A SYNTHESIZED project (e.g. the Nx
+    // workspace-root node, dir === root) has no discovered meta, so the meta
+    // scan alone would miss an existing vx.config.ts at that path and clobber
+    // it. This also covers the extraFiles (vx-preset.ts).
+    for (const f of files) {
+      if (await Bun.file(f.abs).exists()) conflicts.add(f.relPath)
+    }
+    if (conflicts.size > 0) {
+      throw new UserError(
+        'refusing to overwrite existing files (pass --force to overwrite):\n' +
+          `  ${[...conflicts].join('\n  ')}`,
+      )
+    }
+  }
+
+  if (dry) {
+    for (const f of files) {
+      process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
+    }
+  } else {
+    for (const f of files) await Bun.write(f.abs, f.contents)
+  }
+
+  const todoList: string[] = []
+  let clean = 0
+  for (const p of plan.projects) {
+    for (const t of p.tasks) {
+      if (t.todos.length === 0 && t.task !== null) clean++
+      for (const reason of t.todos) todoList.push(`${p.name}#${t.name}: ${reason}`)
+    }
+  }
+  const report: string[] = []
+  // Single-project mode with packages the root's missing `workspaces` never
+  // reaches: the scripts exist, the globs do not (item 248).
+  const unreached = empty ? await unreachedPackages(await loadWorkspace(root)) : []
+  if (empty && unreached.length > 0) {
+    report.push(
+      `${verb}: ${unreachedHint(unreached)}`,
+      hasWorkspaceFile
+        ? `${workspaceName} already exists.`
+        : dry
+          ? `would write ${workspaceName} (dry run, nothing written).`
+          : `wrote ${workspaceName}.`,
+    )
+  } else if (empty) {
+    report.push(
+      `${verb}: no package.json scripts to turn into tasks.`,
+      hasWorkspaceFile
+        ? `${workspaceName} already exists.`
+        : dry
+          ? `would write ${workspaceName} (dry run, nothing written).`
+          : `wrote ${workspaceName}.`,
+      `Declare tasks in a ${configName} beside a package.json — your own command, for example:`,
+      '',
+      ...exampleConfig(format)
+        .trimEnd()
+        .split('\n')
+        .map((l) => `  ${l}`),
+    )
+  } else {
+    report.push(`${verb}: ${source} → ${configName}`)
+    for (const n of args.notes ?? []) report.push(`note: ${n}`)
+    for (const n of plan.headerNotes) report.push(`note: ${n}`)
+    report.push(
+      '',
+      `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
+        `${todoList.length} TODO${todoList.length === 1 ? '' : 's'}${todoList.length > 0 ? ':' : ''}`,
+    )
+    for (const line of todoList) report.push(`  ${line}`)
+    report.push(...plan.notes)
+    report.push(dry ? 'files (dry run, nothing written):' : 'files written:')
+    for (const f of files) report.push(`  ${f.relPath}`)
+  }
+  const firstTask =
+    plan.projects.flatMap((p) => p.tasks.map((t) => t.name)).find((n) => n === 'build') ??
+    plan.projects[0]?.tasks[0]?.name ??
+    'build'
+  report.push('', `next: vx run ${firstTask} --all`)
+  process.stdout.write(`${report.join('\n')}\n`)
+  return 0
+}
+
+const EXAMPLE_BODY = `export default {
+  tasks: {
+    build: {
+      exec: { command: 'tsc -b' },
+      dependsOn: ['^build'],
+      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
+    },
+  },
+}`
+
+function exampleConfig(format: MigrationFormat): string {
+  return format === 'ts'
+    ? `import type { ProjectConfig } from '@vzn/vx'\n\n${EXAMPLE_BODY} satisfies ProjectConfig\n`
+    : `${EXAMPLE_BODY}\n`
+}
+
+// ─── TS emission ──────────────────────────────────────────────────────
+
+// Type-only import + `satisfies`, like the project configs: a runtime
+// `import { defineWorkspace } from '@vzn/vx'` loads a SECOND copy of core
+// into every run — measured 2026-09-09 at ~17 ms on a two-package
+// workspace, a fifth of the whole run — for an identity function.
+const WORKSPACE_BODY = `// Plugins are consulted in this order; running here and caching in
+// .vx/cache are the floor under all of them, so an empty list is a
+// complete workspace. Add a remote cache, a remote executor or telemetry
+// as one entry each — those imports are the runtime ones.
+export default { plugins: [] }`
+
+function workspaceFile(format: MigrationFormat): string {
+  return format === 'ts'
+    ? `import type { WorkspaceConfig } from '@vzn/vx'\n\n${WORKSPACE_BODY} satisfies WorkspaceConfig\n`
+    : `${WORKSPACE_BODY}\n`
+}
+
+const IDENT = /^[A-Za-z_$][\w$]*$/
+
+function isRawExpr(v: unknown): v is RawExpr {
+  return typeof v === 'object' && v !== null && typeof (v as RawExpr).raw === 'string'
+}
+
+function renderValue(v: unknown, indent: string): string {
+  if (isRawExpr(v)) return v.raw
+  // `Object.entries(null)` throws, which would abort the whole migration
+  // with a raw stack mid-write. Mappers no longer produce a null, but a
+  // literal is a readable thing to leave behind if one ever does.
+  if (v === null) return 'null'
+  if (typeof v === 'string') return quoteTsLiteral(v)
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  if (Array.isArray(v)) return `[${v.map((x) => renderValue(x, indent)).join(', ')}]`
+  const entries = Object.entries(v as Record<string, unknown>).filter(([, x]) => x !== undefined)
+  if (entries.length === 0) return '{}'
+  const inner = `${indent}  `
+  const body = entries.map(
+    ([k, x]) => `${inner}${IDENT.test(k) ? k : quoteTsLiteral(k)}: ${renderValue(x, inner)},`,
+  )
+  return `{\n${body.join('\n')}\n${indent}}`
+}
+
+function renderConfigFile(
+  source: string,
+  p: GeneratedProject,
+  verb: string,
+  format: MigrationFormat,
+): string {
+  // A type-only import: the editor type-checks against the installed
+  // package, and Bun erases it, so the config loads in a workspace that
+  // runs the vx binary without the package installed. `mjs` is the same
+  // object with nothing to erase.
+  const lines: string[] = [
+    `// Generated by \`${verb}\` from ${source}. Review the TODO(vx-migrate) comments.`,
+  ]
+  if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx'")
+  if (p.importLines.length > 0) lines.push(...p.importLines)
+  lines.push('', 'export default {', '  tasks: {')
+  for (const t of p.tasks) {
+    for (const todo of t.todos) lines.push(`    // TODO(vx-migrate): ${todo}`)
+    if (t.task === null) continue // skipped target — the TODO above explains
+    const key = IDENT.test(t.name) ? t.name : quoteTsLiteral(t.name)
+    lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
+  }
+  lines.push('  },', format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
+  return lines.join('\n')
+}