@vzn/vx 0.0.645 → 0.0.648

package/src/cli/init.ts

@@ -1,12 +1,12 @@
 // `vx init [--dry [--format json]] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere.
 // It installs vx globally and, where a package.json is, as its devDependency
-// (M, 2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
+// (2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
 // and installs what it writes (`migrate`); any other gets the workspace file
 // and an empty root project, then the lock (`starter`).
-// `vx init --plugin <seam>` writes a runnable plugin for one seam and its
+// `vx init --plugin <hook>` writes a runnable plugin for one hook and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { gitTop, workspaceFileWritten } from '../handoff.js'
@@ -22,11 +22,23 @@ import {
   type ManagedInstall,
 } from './upgrade.js'
 import { VERSION } from '../version.js'
-import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
+import {
+  detectColors,
+  DOT_VX_GITATTRIBUTES,
+  DOT_VX_GITIGNORE,
+  paint,
+  refuseSymlink,
+  sayNotice,
+  SUCCESS,
+  ui,
+  UserError,
+  writeNoFollow,
+} from '../util/index.js'
 import {
   findWorkspaceRoot,
   PROJECT_CONFIG_FILENAMES,
-  vxInvocation,
+  renderWorkspace,
+  starterProject,
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
@@ -35,7 +47,7 @@ interface InitArgs {
   force: boolean
   /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
   mjs: boolean
-  /** `--plugin <seam>`: scaffold that seam's plugin instead of the workspace. */
+  /** `--plugin <hook>`: scaffold that hook's plugin instead of the workspace. */
   plugin?: string
   /** `--native` / `--keep` in a Turbo or Nx repo; unset, vx-migrate asks a terminal. */
   mode?: 'native' | 'keep'
@@ -54,7 +66,16 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
       if (seam === undefined || !Object.hasOwn(PLUGIN_TEMPLATES, seam)) {
         return {
           ...out,
-          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}${seeHelp('init')}`,
+          error:
+            seam === undefined || seam === ''
+              ? `--plugin requires a value: one of ${seams}${seeHelp('init')}`
+              : `--plugin must be one of ${seams} (got ${seam})${seeHelp('init')}`,
+        }
+      }
+      if (out.plugin !== undefined && out.plugin !== seam) {
+        return {
+          ...out,
+          error: `--plugin takes one hook; run vx init --plugin once per hook${seeHelp('init')}`,
         }
       }
       out.plugin = seam
@@ -117,16 +138,47 @@ export async function initCmd(args: readonly string[]): Promise<number> {
   if (dirs.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
     return migrate(dirs, parsed)
   }
-  // The topmost package.json: a monorepo's root, wherever below it init ran.
-  const pkgRoot = dirs.findLast((d) => existsSync(path.join(d, 'package.json'))) ?? null
+  const pkgRoot = packageRoot(dirs, top !== null)
   return starter(marked ?? pkgRoot ?? cwd, pkgRoot, top === null, parsed)
 }
 
+/**
+ * Inside git, the topmost package.json: a monorepo's root, wherever below
+ * it init ran. Outside git `dirs` reach `/`, and the topmost took a stray
+ * package.json in the home directory (2026-10-28); there it is the nearest
+ * one, or the outermost above it that declares a workspace.
+ */
+function packageRoot(dirs: readonly string[], inGit: boolean): string | null {
+  const has = (d: string, f: string): boolean => existsSync(path.join(d, f))
+  if (inGit) return dirs.findLast((d) => has(d, 'package.json')) ?? null
+  const at = dirs.findIndex((d) => has(d, 'package.json'))
+  if (at === -1) return null
+  const outer = dirs
+    .slice(at + 1)
+    .findLast(
+      (d) => has(d, 'package.json') && (has(d, 'pnpm-workspace.yaml') || declaresWorkspaces(d)),
+    )
+  return outer ?? dirs[at]!
+}
+
+function declaresWorkspaces(dir: string): boolean {
+  try {
+    const pj = JSON.parse(
+      readFileSync(path.join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''),
+    ) as {
+      workspaces?: unknown
+    }
+    return pj.workspaces !== undefined
+  } catch {
+    return false
+  }
+}
+
 /** What makes a repo vx-migrate's to map: a Turbo or Nx config. */
 const TOOL_CONFIGS = ['turbo.json', 'turbo.jsonc', 'nx.json']
 
 /**
- * The installs `vx init` runs (M, 2026-10-20): vx at `version` globally,
+ * The installs `vx init` runs (2026-10-20): vx at `version` globally,
  * with the manager that started init, so a bare `vx` is on PATH, unless
  * the global vx already answers `version`; and, where `pkgRoot` has a
  * package.json, as its devDependency with the repo's own manager.
@@ -137,10 +189,13 @@ export function initInstalls(
   pkgRoot: string | null,
   globalAt: string | undefined,
   execPath = process.execPath,
+  plugins: readonly string[] = [],
 ): { argv: string[]; cwd: string | null }[] {
   const out: { argv: string[]; cwd: string | null }[] = []
   if (globalAt !== version) {
-    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'npm'
+    // Yarn 2+ has no `yarn global`: Bun, which vx needs anyway, as with no runner.
+    const ua = /^(npm|pnpm|yarn|bun)\/(\d+)/.exec(userAgent ?? '')
+    const runner = ua === null || (ua[1] === 'yarn' && Number(ua[2]) >= 2) ? 'bun' : ua[1]!
     const manager = runner as ManagedInstall['manager']
     out.push({ argv: upgradeArgv({ manager, scope: 'global', cwd: '' }, version), cwd: null })
   }
@@ -150,6 +205,7 @@ export function initInstalls(
       scope: 'project',
       cwd: pkgRoot,
       field: 'devDependencies',
+      plugins: [...plugins],
     }
     out.push({ argv: upgradeArgv(install, version), cwd: pkgRoot })
   }
@@ -168,11 +224,30 @@ function globalVersion(): string | undefined {
   return undefined
 }
 
+/**
+ * The package a manager's output says the registry answered 404 for, as
+ * `name@version`: a release's platform tarball stays unserved for minutes
+ * after publish (v0.0.646, 2026-10-23). bun: `GET <url> - 404`; npm:
+ * `404 Not Found - GET <url>`; pnpm: `GET <url>: Not Found - 404`.
+ */
+export function notServed(output: string): string | undefined {
+  for (const line of output.split('\n')) {
+    if (!line.includes('404')) continue
+    const m = /https?:\/\/\S+?\/((?:@[^/\s]+\/)?[^/\s]+)\/-\/[^/\s]+?-(\d[^/\s]*?)\.tgz/.exec(line)
+    if (m !== null) return `${decodeURIComponent(m[1]!)}@${m[2]}`
+  }
+  return undefined
+}
+
 /**
  * Run `initInstalls`, in order. A source checkout (0.0.0, which npm never
  * had) installs nothing: the release would replace the code under test.
  */
-async function install(pkgRoot: string | null, dry: boolean): Promise<string[]> {
+async function install(
+  pkgRoot: string | null,
+  dry: boolean,
+  plugins: readonly string[] = [],
+): Promise<string[]> {
   if (VERSION === '0.0.0') return []
   const version = await targetVersion(undefined, 'vx init')
   const steps = initInstalls(
@@ -180,6 +255,8 @@ async function install(pkgRoot: string | null, dry: boolean): Promise<string[]>
     process.env['npm_config_user_agent'],
     pkgRoot,
     globalVersion(),
+    process.execPath,
+    plugins,
   )
   if (dry) return steps.map((s) => s.argv.join(' '))
   for (const s of steps) {
@@ -193,22 +270,62 @@ async function install(pkgRoot: string | null, dry: boolean): Promise<string[]>
       'out',
       ui.text([ui.cmd(s.argv.join(' ')), ui.dim(s.cwd === null ? '' : ` in ${s.cwd}`)]),
     )
-    const proc = Bun.spawnSync({
+    const proc = Bun.spawn({
       cmd: [bin, ...s.argv.slice(1)],
       cwd: s.cwd ?? process.cwd(),
-      stdio: ['inherit', 'inherit', 'inherit'],
+      stdio: ['inherit', 'inherit', 'pipe'],
     })
-    if (proc.exitCode !== 0) {
-      throw new UserError(`vx init: ${s.argv.join(' ')} failed (exit ${proc.exitCode})`)
+    // Shown as it comes, and kept: a registry 404 is the cause to name.
+    let said = ''
+    const decoder = new TextDecoder()
+    for await (const chunk of proc.stderr) {
+      process.stderr.write(chunk)
+      said += decoder.decode(chunk, { stream: true })
+    }
+    const code = await proc.exited
+    if (code !== 0) {
+      const missing = notServed(said)
+      throw new UserError(
+        missing === undefined
+          ? `vx init: ${s.argv.join(' ')} failed (exit ${code})`
+          : `vx init: the npm registry does not serve ${missing} yet (404), as a release can take minutes to reach it; run bunx @vzn/vx init again`,
+      )
     }
   }
   return steps.map((s) => s.argv.join(' '))
 }
 
+const PLUGINS_MANIFEST = `${JSON.stringify({ name: 'workspace-plugins', private: true }, null, 2)}\n`
+
+/** Whether the nearest package.json above `dir` has a name, as `definePlugin` needs. */
+function ownerNamed(dir: string): boolean {
+  for (let d = dir; ; d = path.dirname(d)) {
+    let text: string
+    try {
+      text = readFileSync(path.join(d, 'package.json'), 'utf8').replace(/^/, '')
+    } catch {
+      if (path.dirname(d) === d) return false
+      continue
+    }
+    try {
+      const name = (JSON.parse(text) as { name?: unknown } | null)?.name
+      return typeof name === 'string' && name !== ''
+    } catch {
+      return false
+    }
+  }
+}
+
 /** Write `plugins/<seam>.ts` and its test under `root`: the workspace root, else the cwd. */
 async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promise<number> {
   const template = PLUGIN_TEMPLATES[seam]!
+  // `definePlugin` names the plugin by the nearest package.json, and a
+  // monorepo root often has no name: the plugin refused to load.
+  const manifest: [string, string][] = ownerNamed(path.join(root, 'plugins'))
+    ? []
+    : [[path.join('plugins', 'package.json'), PLUGINS_MANIFEST]]
   const files = [
+    ...manifest,
     [path.join('plugins', `${seam}.ts`), template.plugin],
     [path.join('plugins', `${seam}.test.ts`), template.test],
   ] as const
@@ -221,24 +338,69 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
     }
   }
   if (!args.dry) {
-    await mkdir(path.join(root, 'plugins'), { recursive: true })
+    await mkdir(path.join(root, 'plugins'), { recursive: true }).catch(
+      (err: NodeJS.ErrnoException) => {
+        if (err.code !== 'EEXIST' && err.code !== 'ENOTDIR') throw err
+        throw new UserError(
+          `vx init: cannot write ${files[0][0]}: plugins is a file, not a directory; move it and re-run`,
+        )
+      },
+    )
     for (const [rel, text] of files) await Bun.write(path.join(root, rel), text)
   }
   const factory = /^export function (\w+)/m.exec(template.plugin)![1]!
   const workspaceFile =
     WORKSPACE_CONFIG_FILENAMES.find((n) => existsSync(path.join(root, n))) ?? '.vx/workspace.ts'
+  const c = detectColors(process.stdout)
+  const dim = (t: string): string => paint('', t, c, { dim: true })
+  const bold = (t: string): string => paint('', t, c, { bold: true })
   process.stdout.write(
-    `${args.dry ? 'would write' : 'wrote'} ${files.map(([rel]) => rel).join(' and ')}\n` +
-      `Declare it in ${workspaceFile}: import { ${factory} } from '../plugins/${seam}.ts', then plugins: [${factory}(…)]\n` +
-      `Test it: bun test plugins/${seam}.test.ts (needs @vzn/vx installed)\n`,
+    `${paint(SUCCESS, args.dry ? 'would write' : 'wrote', c, { bold: true })} ${files.map(([rel]) => bold(rel)).join(' and ')}\n` +
+      `${dim('Declare it in')} ${workspaceFile}${dim(':')} ${bold(`import { ${factory} } from '../plugins/${seam}.ts'`)}${dim(', then')} ${bold(`plugins: [${factory}(…)]`)}\n` +
+      `${dim('Test it:')} ${bold(`bun test plugins/${seam}.test.ts`)} ${dim('(needs @vzn/vx installed)')}\n`,
   )
   return 0
 }
 
-const WORKSPACE =
-  "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
-const PROJECT =
-  "import { defineProject } from '@vzn/vx'\n\nexport default defineProject({ tasks: {} })\n"
+/**
+ * The `@vzn/vx-lockfile` plugin the lockfile at `pkgRoot` calls for: without
+ * it a JS workspace has no project edges, and the first `^build` a user
+ * writes is refused at `vx lock`.
+ */
+function lockfilePlugin(pkgRoot: string | null): 'pnpm' | 'bun' | 'yarn' | 'npm' | null {
+  if (pkgRoot === null) return null
+  const has = (f: string): boolean => existsSync(path.join(pkgRoot, f))
+  if (has('pnpm-lock.yaml')) return 'pnpm'
+  if (has('bun.lock') || has('bun.lockb')) return 'bun'
+  if (has('yarn.lock')) return 'yarn'
+  if (has('package-lock.json') || has('npm-shrinkwrap.json')) return 'npm'
+  return null
+}
+
+/**
+ * Whether `pkgRoot` has package.json scripts to map: its own, or a
+ * workspace's members (`workspaces`, `pnpm-workspace.yaml`). Core maps none
+ * (2026-10-20), so `next` names the tool that does.
+ */
+function hasScripts(pkgRoot: string | null): boolean {
+  if (pkgRoot === null) return false
+  if (existsSync(path.join(pkgRoot, 'pnpm-workspace.yaml'))) return true
+  try {
+    // A byte-order mark is stripped, as npm strips it.
+    const pj = JSON.parse(
+      readFileSync(path.join(pkgRoot, 'package.json'), 'utf8').replace(/^/, ''),
+    ) as {
+      scripts?: unknown
+      workspaces?: unknown
+    }
+    return (
+      pj.workspaces !== undefined ||
+      (typeof pj.scripts === 'object' && pj.scripts !== null && Object.keys(pj.scripts).length > 0)
+    )
+  } catch {
+    return false
+  }
+}
 
 /**
  * No Turbo or Nx config: the installs, then `.vx/workspace.ts` declaring
@@ -255,17 +417,31 @@ async function starter(
   if (args.mode !== undefined) {
     throw new UserError(
       `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no turbo.json or nx.json here`,
+      'VX_E_USAGE',
     )
   }
-  const installs = args.json === true || args.dry ? await install(pkgRoot, true) : []
+  // A source checkout installs nothing, so it declares the plugin only where one is.
+  const found = lockfilePlugin(pkgRoot)
+  const plugin =
+    found !== null &&
+    (VERSION !== '0.0.0' ||
+      existsSync(path.join(pkgRoot!, 'node_modules', '@vzn', 'vx-lockfile', 'package.json')))
+      ? found
+      : null
+  const plugins = plugin === null ? [] : ['@vzn/vx-lockfile']
+  const installs = args.json === true || args.dry ? await install(pkgRoot, true, plugins) : []
   const ext = args.mjs ? 'mjs' : 'ts'
   const config = `vx.config.${ext}`
   const files: { path: string; contents: string }[] = []
   const kept: string[] = []
   const replaced: string[] = []
   for (const [names, name, contents] of [
-    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, WORKSPACE],
-    [PROJECT_CONFIG_FILENAMES, config, PROJECT],
+    [
+      WORKSPACE_CONFIG_FILENAMES,
+      `.vx/workspace.${ext}`,
+      renderWorkspace(ext, plugin === null ? [] : [{ pkg: '@vzn/vx-lockfile', factory: plugin }]),
+    ],
+    [PROJECT_CONFIG_FILENAMES, config, starterProject(ext)],
   ] as const) {
     const existing = names.find((n) => existsSync(path.join(root, n)))
     if (existing !== undefined && !args.force) kept.push(existing)
@@ -281,8 +457,8 @@ async function starter(
   ] as const) {
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
-  const vx = VERSION === '0.0.0' ? vxInvocation(process.env['npm_config_user_agent'], false) : 'vx'
-  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then ${vx} lock && ${vx} run <task>`
+  const declare = `declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then vx lock && vx run <task>`
+  const next = `${noGit ? 'git init, ' : ''}${hasScripts(pkgRoot) ? `bunx @vzn/vx-migrate${args.mjs ? ' --mjs' : ''} to make package.json scripts tasks, or ${declare}` : declare}`
   if (args.json === true) {
     process.stdout.write(
       `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
@@ -290,19 +466,30 @@ async function starter(
     return 0
   }
   const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json: one project, the root']]
+  // The files are root-relative: a root above the cwd is named, or they read as written here.
+  if (root !== process.cwd()) rows.push(['root', root])
   if (args.dry) rows.push(['dry run', 'nothing written'])
   if (installs.length > 0) rows.push(['install', ...installs])
   if (files.length > 0) rows.push(['files', ...files.map((f) => f.path)])
   if (kept.length > 0) rows.push(['kept', ...kept])
   if (replaced.length > 0) rows.push(['replaced', ...replaced])
   if (args.dry) {
-    for (const f of files) process.stdout.write(`── ${f.path} ──\n${f.contents}\n`)
+    for (const f of files) ui.print('out', ui.excerpt(f.path, f.contents))
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
-  const ran = await install(pkgRoot, false)
+  for (const f of files) refuseSymlink(path.join(root, f.path))
+  const ran = await install(pkgRoot, false, plugins)
   if (ran.length > 0) rows.push(['installed', ...ran])
-  for (const f of files) await Bun.write(path.join(root, f.path), f.contents)
+  for (const f of files) {
+    await writeNoFollow(path.join(root, f.path), f.contents).catch((err: NodeJS.ErrnoException) => {
+      // writeNoFollow's mkdir of a parent that is a file says EEXIST.
+      if (err.code !== 'ENOTDIR' && err.code !== 'EEXIST') throw err
+      throw new UserError(
+        `vx init: cannot write ${f.path}: ${path.dirname(f.path)} is a file, not a directory; move it and re-run`,
+      )
+    })
+  }
   for (const f of replaced) await unlink(path.join(root, f))
   // The lock that follows loads the workspace file just written.
   workspaceFileWritten()
@@ -312,14 +499,15 @@ async function starter(
     lock.code === 0 ? next : `fix the above, then vx lock and ${next}`,
   ])
   ui.print('out', ui.report(`vx init ${VERSION}`, rows))
-  return 0
+  // A run reads only the lock: init without one is not done, as vx-migrate exits.
+  return lock.code === 0 ? 0 : 1
 }
 
 /**
  * A Turbo or Nx repo is `@vzn/vx-migrate`'s, after the global install, at the latest
  * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
  * at its own version, so init always lands on latest with all of them
- * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
+ * together, as `vx upgrade` moves them (2026-10-16: an installed 0.0.637
  * pinned core back from 0.0.639). It finds the root itself, asks a
  * terminal native or keep in a Turbo or Nx repo, and installs what it writes.
  */