@vzn/vx 0.0.141 → 0.0.143

package/README.md

@@ -32,7 +32,8 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 
 ## Try it on your repo
 
-In a Turborepo or Nx workspace, add one file:
+In a Turborepo or Nx workspace, add one file (`npx @vzn/vx init` writes
+it and prints the command to run next):
 
 ```ts
 // vx.workspace.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.141",
+  "version": "0.0.143",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.141",
-    "@vzn/vx-linux-arm64": "0.0.141",
-    "@vzn/vx-darwin-x64": "0.0.141",
-    "@vzn/vx-darwin-arm64": "0.0.141"
+    "@vzn/vx-linux-x64": "0.0.143",
+    "@vzn/vx-linux-arm64": "0.0.143",
+    "@vzn/vx-darwin-x64": "0.0.143",
+    "@vzn/vx-darwin-arm64": "0.0.143"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/archive.ts

@@ -38,7 +38,7 @@
 // otherwise silently loses the claim rather than acting on it.
 
 import { chmodSync, renameSync, statSync, utimesSync } from 'node:fs'
-import { mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
@@ -193,6 +193,13 @@ export interface PackArgs {
   outputs: ReadonlyMap<string, string>
   /** The producing execution's usage, when the runner reported it. */
   exec?: ExecUsage | undefined
+  /**
+   * The project directory a symlinked output must resolve inside. vx reads
+   * outputs outside the task's sandbox, so a link a sandboxed task planted
+   * to a file it could not read (another project's, the user's home) packed
+   * that file into the artifact and the remote (L-23).
+   */
+  within?: string
 }
 
 /** A packed artifact's plan: its entries with their stats, and the tar's exact size. */
@@ -206,11 +213,12 @@ export interface ArtifactPlan {
  * mtime) and lay out the tar — stdout first, the outputs, the sidecar
  * last — with its exact size, so the caller can choose the one-call pack
  * for a small artifact and the streamed one for a large one before a
- * byte is read. A symlinked output is stored as its target's content, as
- * it always was.
+ * byte is read. A symlinked output is stored as its target's content,
+ * when that target is inside `within`.
  */
 export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
   const meta: MetaFile = { version: 1, files: {} }
+  let withinReal: Promise<string> | undefined
   if (args.key !== undefined) meta.key = args.key
   const exec = usageOf(args.exec)
   if (exec !== undefined) meta.exec = exec
@@ -221,14 +229,31 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       // directory, or a dangling one, has no bytes to pack: refuse loudly
       // rather than store an entry that restores to nothing.
       const shown = name.startsWith('outputs/') ? name.slice('outputs/'.length) : name
-      const st = await stat(abs).catch((err: NodeJS.ErrnoException) => {
+      const dangling = (err: NodeJS.ErrnoException): never => {
         if (err.code === 'ENOENT') {
           throw new UserError(
             `output ${shown} is a dangling symlink: vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
           )
         }
         throw err
-      })
+      }
+      // lstat, so a regular file costs no second call; only a link is
+      // resolved, and its body is read from the path this check resolved.
+      let src = abs
+      let st = await lstat(abs)
+      if (st.isSymbolicLink()) {
+        src = await realpath(abs).catch(dangling)
+        if (args.within !== undefined) {
+          withinReal ??= realpath(args.within)
+          const root = await withinReal
+          if (!src.startsWith(root + path.sep)) {
+            throw new UserError(
+              `output ${shown} is a symlink to ${src}, outside the project: vx packs a symlinked output as its target's bytes, and a project's outputs come from its own directory — emit a file there, or take it back with a '!' entry`,
+            )
+          }
+        }
+        st = await stat(src).catch(dangling)
+      }
       if (!st.isFile()) {
         throw new UserError(
           `output ${shown} is not a regular file (a symlink to a directory?): vx stores regular files only — emit a file there, or narrow cache.outputs.files to the files the task produces, or take it back with a '!' entry`,
@@ -240,7 +265,7 @@ export async function planArtifact(args: PackArgs): Promise<ArtifactPlan> {
       meta.files[name] = [mode, Math.floor(st.mtimeMs)]
       return {
         name,
-        abs,
+        abs: src,
         size: st.size,
         mode,
         // ustar's octal field holds no sign: an mtime before 1970 made the

package/src/cache/cache.ts

@@ -1304,6 +1304,7 @@ export class Cache implements CacheLayer {
       stdout: args.entry.stdout ?? '',
       outputs: this.outputsOf(args),
       exec: usageOfEntry(args.entry),
+      within: args.projectDir,
     })
     if (plan.size > this.artifactCeiling) {
       throw new Error(

package/src/cli/help.ts

@@ -157,7 +157,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Migration:',
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
     '                       from package.json scripts. Unmappable settings become',
-    '                       TODO(vx-migrate) comments.',
+    '                       TODO(vx-migrate) comments. Beside turbo.json or nx.json:',
+    '                       only vx.workspace.ts, declaring turbo() or nx().',
     '      --dry            Print the generated files instead of writing them.',
     '      --force          Overwrite existing vx.config.* files.',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',

package/src/cli/init.ts

@@ -5,7 +5,8 @@
 // `vx init --plugin <seam>` writes a runnable plugin for one seam and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
-import { mkdir } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
@@ -17,6 +18,7 @@ import {
   listProjects,
   loadWorkspace,
   migrateScripts,
+  WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
 export interface InitArgs {
@@ -76,7 +78,6 @@ export async function initCmd(args: readonly string[]): Promise<number> {
   // richer source (dependsOn, inputs, outputs) and was ignored without a
   // word — the walkthrough on a Turbo repo (2026-09-09) got the scripts'
   // TODOs and none of the edges turbo.json already declared.
-  const notes: string[] = []
   // Turbo 2.5+ reads `turbo.jsonc` as well (item 938).
   let turbo: string | undefined
   for (const name of ['turbo.json', 'turbo.jsonc']) {
@@ -85,21 +86,14 @@ export async function initCmd(args: readonly string[]): Promise<number> {
       break
     }
   }
-  if (turbo !== undefined) {
-    notes.push(
-      `${turbo} found and not read — ` +
-        '`bunx @vzn/vx-migrate` maps it (dependsOn, inputs, ' +
-        'outputs), or `plugins: [turbo()]` from @vzn/vx-migrate runs it with nothing written',
-    )
-  } else if (
-    (await Bun.file(path.join(root, 'nx.json')).exists()) ||
-    (await Bun.file(path.join(root, '.nx', 'workspace-data', 'project-graph.json')).exists())
-  ) {
-    notes.push(
-      'an Nx workspace found and not read — `bunx @vzn/vx-migrate --from nx` maps its ' +
-        'exported project graph, or `plugins: [nx()]` from @vzn/vx-migrate runs it with ' +
-        'nothing written',
-    )
+  // A Turbo or Nx repo already says its tasks: the runner's own config is
+  // the source, and `turbo()` / `nx()` read it live. Writing a config per
+  // package from the scripts dropped every edge turbo.json declares (the
+  // first-five-minutes walk, 2026-09-28); the workspace file alone is the
+  // whole adoption, and `bunx @vzn/vx-migrate` stays for freezing it.
+  if (turbo !== undefined) return adopt(root, 'turbo', turbo, parsed)
+  if (await Bun.file(path.join(root, 'nx.json')).exists()) {
+    return adopt(root, 'nx', 'nx.json', parsed)
   }
   return applyMigration({
     root,
@@ -110,7 +104,6 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     dry: parsed.dry,
     force: parsed.force,
     init: true,
-    notes,
     format: parsed.mjs ? 'mjs' : 'ts',
   })
 }
@@ -143,3 +136,92 @@ async function scaffoldPlugin(seam: string, args: InitArgs): Promise<number> {
   )
   return 0
 }
+
+/**
+ * `vx init` in a Turbo or Nx repo: `vx.workspace.ts` declaring the plugin
+ * that runs the repo as it is, nothing else, and the one command that gets
+ * from here to a run.
+ */
+async function adopt(
+  root: string,
+  runner: 'turbo' | 'nx',
+  source: string,
+  args: InitArgs,
+): Promise<number> {
+  const name = `vx.workspace.${args.mjs ? 'mjs' : 'ts'}`
+  const body = `import { ${runner} } from '@vzn/vx-migrate'\n\nexport default { plugins: [${runner}()] }`
+  const text = args.mjs
+    ? `${body}\n`
+    : `import type { WorkspaceConfig } from '@vzn/vx'\n${body} satisfies WorkspaceConfig\n`
+  const existing = WORKSPACE_CONFIG_FILENAMES.find((f) => existsSync(path.join(root, f)))
+  if (existing !== undefined && !args.force) {
+    const declared = readFileSync(path.join(root, existing), 'utf8').includes(`${runner}(`)
+    if (!declared) {
+      throw new UserError(
+        `vx init: ${existing} exists; add ${runner}() from @vzn/vx-migrate to its plugins, or --force replaces it`,
+      )
+    }
+  } else if (args.dry) {
+    process.stdout.write(`── ${name} ──\n${text}\n`)
+  } else {
+    if (existing !== undefined && existing !== name) await unlink(path.join(root, existing))
+    await Bun.write(path.join(root, name), text)
+  }
+  const wrote =
+    existing !== undefined && !args.force
+      ? `${existing} already declares ${runner}().`
+      : args.dry
+        ? `would write ${name} (dry run, nothing written).`
+        : `wrote ${name}.`
+  process.stdout.write(
+    `vx init: ${source} found — ${runner}() from @vzn/vx-migrate runs this repo as it is; nothing else written.\n` +
+      `${wrote}\n\nnext: ${adoptionNext(root, runner, source)}\n`,
+  )
+  return 0
+}
+
+type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm'
+
+const LOCKFILES: ReadonlyArray<[string, PackageManager]> = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['bun.lock', 'bun'],
+  ['bun.lockb', 'bun'],
+  ['package-lock.json', 'npm'],
+]
+
+const INSTALL: Record<PackageManager, string> = {
+  pnpm: 'pnpm add -D -w',
+  yarn: 'yarn add -D',
+  bun: 'bun add -d',
+  npm: 'npm install -D',
+}
+
+const EXEC: Record<PackageManager, string> = { pnpm: 'pnpm', yarn: 'yarn', bun: 'bunx', npm: 'npx' }
+
+/** Install what the workspace file imports, if missing, then run the repo's build. */
+export function adoptionNext(root: string, runner: 'turbo' | 'nx', source: string): string {
+  const pm = LOCKFILES.find(([f]) => existsSync(path.join(root, f)))?.[1] ?? 'npm'
+  const missing = ['@vzn/vx', '@vzn/vx-migrate'].filter(
+    (p) => !existsSync(path.join(root, 'node_modules', p, 'package.json')),
+  )
+  // A global vx (no runner started this one) runs the workspace's plugins as they are.
+  const vx = process.env['npm_config_user_agent'] === undefined ? 'vx' : `${EXEC[pm]} vx`
+  const task = firstTask(path.join(root, source), runner)
+  const run = `${vx} run ${task} --all`
+  return missing.length === 0 ? run : `${INSTALL[pm]} ${missing.join(' ')} && ${run}`
+}
+
+/** `build` when the runner's config names it, else the first task it names. */
+function firstTask(file: string, runner: 'turbo' | 'nx'): string {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return 'build'
+  }
+  if (/"build"\s*:/.test(text)) return 'build'
+  const field = runner === 'turbo' ? '(?:tasks|pipeline)' : 'targetDefaults'
+  const first = new RegExp(`"${field}"\\s*:\\s*\\{\\s*"([^"]+)"`).exec(text)?.[1]
+  return first ?? 'build'
+}