@vzn/vx 0.0.651 → 0.0.653

package/src/cli/core-alias.ts

@@ -9,7 +9,10 @@
  * and two module states — two `definePlugin` memos, two of everything
  * keyed by identity rather than by registry symbol.
  *
- * The alias is a Bun virtual module for the exact specifier `@vzn/vx`,
+ * The alias is a Bun virtual module for the exact specifiers `@vzn/vx`
+ * and `@vzn/vx/config` (the second for `import { defineProject }` in a
+ * config: with a node_modules and no `@vzn/vx` in it, the import failed
+ * though the page says vx runs a config without it),
  * served from the host's own façade, loaded lazily on the first import
  * so a verb that never loads a plugin never loads the façade. The
  * source form (`bun src/bin.ts`) resolves the specifier to the same file
@@ -18,11 +21,15 @@
  * (workspace/config-bytecode.ts) is CommonJS, and `require` refuses a
  * module whose loader is async.
  */
-export function registerCoreAlias(load: () => Record<string, unknown>): void {
+export function registerCoreAlias(
+  load: () => Record<string, unknown>,
+  loadConfig: () => Record<string, unknown>,
+): void {
   Bun.plugin({
     name: 'vx-core-alias',
     setup(build) {
       build.module('@vzn/vx', () => ({ exports: load(), loader: 'object' }))
+      build.module('@vzn/vx/config', () => ({ exports: loadConfig(), loader: 'object' }))
     },
   })
 }

package/src/cli/docs.ts

@@ -31,10 +31,12 @@ export function parseDocsArgs(args: readonly string[]): DocsArgs {
       out.json = fv === 'json'
     } else if (a === '--limit' || a.startsWith('--limit=')) {
       const v = a === '--limit' ? args[++i] : a.slice('--limit='.length)
-      if (v === undefined || v === '') {
+      // The space form took the next flag as the count and refused it as one.
+      const flag = a === '--limit' && v !== undefined && /^-\D/.test(v) ? ` (got flag ${v})` : ''
+      if (v === undefined || v === '' || flag !== '') {
         return {
           ...out,
-          error: `--limit requires a value: a whole number above 0${seeHelp('docs')}`,
+          error: `--limit requires a value: a whole number above 0${flag}${seeHelp('docs')}`,
         }
       }
       const n = parseDecimalInt(v)

package/src/cli/help.ts

@@ -90,12 +90,33 @@ export function verbHelpText(verb: string): string {
       if (own.length > 0) kept.push(['Usage:', ...own].join('\n'))
       continue
     }
-    if (lines.some(names)) kept.push(block)
+    if (lines.some(names)) kept.push(own(lines, names, quoted))
   }
   if (kept.length === 0) return helpText()
   return [title, ...kept, 'Full reference: vx help', ''].join('\n\n')
 }
 
+/**
+ * A section's entries for one verb, when the section holds several verbs'
+ * entries (Introspection): an entry is a two-space line and the deeper
+ * lines under it; a shared one (`info, why and last:`) stays if it names
+ * the verb. A one-verb or `(for <verb>)` section stays whole.
+ */
+function own(lines: string[], names: (line: string) => boolean, quoted: string): string {
+  const entries: string[][] = []
+  for (const line of lines.slice(1)) {
+    if (/^ {2}\S/.test(line) || entries.length === 0) entries.push([line])
+    else entries.at(-1)!.push(line)
+  }
+  const verbs = new Set(entries.map((e) => /^ {2}vx ([\w-]+)/.exec(e[0]!)?.[1]).filter(Boolean))
+  if (verbs.size < 2) return lines.join('\n')
+  const word = new RegExp(`\\b${quoted}\\b`)
+  const mine = entries.filter(
+    (e) => names(e[0]!) || (!e[0]!.startsWith('  vx ') && word.test(e[0]!)),
+  )
+  return [lines[0]!, ...mine.flat()].join('\n')
+}
+
 export function helpText(pluginCommands: readonly string[] = []): string {
   return [
     'vx — task orchestration you own',
@@ -141,7 +162,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --no-cache                  No cache reads or writes; outputs are left',
     '                                  alone.',
     '      --force                     Skip cache reads but still write: every task',
-    '                                  runs and refreshes its entry.',
+    '                                  runs; a key already stored is kept.',
     '      --cache-policy <spec>       Per-layer read/write: a comma list of',
     '                                  <layer>:<flags> (layer local or remote, flags',
     '                                  from rw). A named layer is set to exactly its',
@@ -204,9 +225,9 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     'Cache management:',
     '  vx cache clean --older-than 30d     Evict entries last accessed > 30 days ago.',
     '  vx cache clean --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
-    "  vx cache clean                      Clear .vx/cache and this repo's store",
+    "  vx cache clean                      Clear .vx/cache and this workspace's store",
     '                                      ~/.vx/<id>/cache.',
-    "      --global                        Clear every repo's store under ~/.vx.",
+    "      --global                        Clear every workspace's store under ~/.vx.",
     '      --dry                           Say what the policy would reap; delete nothing.',
     '      --format <fmt>                  pretty (default) | json.',
     '      --cache-dir <path>              The cache a run with the same flag uses (why,',
@@ -366,6 +387,8 @@ export function flagHint(verb: string, arg: string): string {
   // `--json` is gh's and Nx's spelling; a verb with `--format` reads it
   // there, and no edit budget reaches `--format json` from `--json`.
   if (name === '--json' && flags.includes('--format')) return ' (did you mean --format json?)'
+  // pnpm's and Turbo's short `--filter`.
+  if (name === '-F') return flags.includes('--filter') ? ' (did you mean --filter?)' : ''
   // `vx run` prints no JSON of its own, and edit distance reached `--force`
   // from `--format`: a run with its cache reads turned off.
   if ((name === '--format' || name === '--json') && flags.includes('--dry'))

package/src/cli/index.ts

@@ -6,6 +6,7 @@ import { checkSettingsEnv } from '../settings.js'
 import { CORE_VERBS, flagHint, printHelp, refuse, refusedWord, seeHelp } from './help.js'
 import {
   errorDocument,
+  hasControl,
   hideEnvFromTasks,
   isFsRefusal,
   isOutOfFds,
@@ -30,6 +31,7 @@ const plugins = () => import('./plugin-commands.js')
 export async function run(argv: readonly string[]): Promise<number> {
   refuseLossyArgs(argv)
   const [command, ...rest] = argv
+  if (command !== undefined) refuseControlArgs(command, rest)
   await hideEnvFromTasks()
 
   // `vx <verb> --help` is the universal reflex, and every verb answered
@@ -41,12 +43,21 @@ export async function run(argv: readonly string[]): Promise<number> {
     await printHelp(await (await plugins()).pluginCommandHelp(), command)
     return 0
   }
+  if (command !== undefined && forwardsNothing(command, rest)) {
+    return refuse(
+      command,
+      rest,
+      'forwards nothing after -- (only vx run and vx watch pass arguments on to a task)',
+      'VX_E_USAGE',
+    )
+  }
   // Each setting's variable once, before any verb: a renamed one is named,
   // and a deep reader trusts what it reads. Not for help, as `vx run
   // --help` above is not: help is where a setting's values are read. Nor
-  // for `vx info`, which reports a refused one (doctor.ts).
+  // for `vx info`, which reports a refused one (doctor.ts). Nor for one
+  // whose flag is given: the flag beats it.
   if (command !== 'help' && command !== '--help' && command !== '-h' && command !== 'info')
-    checkSettingsEnv()
+    checkSettingsEnv(process.env, rest)
 
   try {
     return await dispatch(command, rest)
@@ -69,6 +80,43 @@ function refuseLossyArgs(argv: readonly string[]): void {
   )
 }
 
+/**
+ * No core verb's argument holds a control character, and a refusal echoing
+ * one raw broke its headline at a newline. A forwarded one (after `--`) is
+ * the task's, a `--sql` query may span lines, and a plugin verb owns its own.
+ */
+function refuseControlArgs(command: string, rest: readonly string[]): void {
+  if (!(CORE_VERBS as readonly string[]).includes(command)) return
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!
+    if (a === '--') return
+    if (a === '--sql') {
+      i++
+      continue
+    }
+    if (a.startsWith('--sql=') || !hasControl(a)) continue
+    throw new UserError(
+      `argument ${i + 2} (${JSON.stringify(a)}) holds a control character, which no \`vx ${command}\` argument takes`,
+      'VX_E_USAGE',
+    )
+  }
+}
+
+/**
+ * A `--` given to a core verb that hands no task its words: each parser
+ * refused it as `unknown flag: --`, true of no flag. A `--sql` query is
+ * the one value that may be `--`.
+ */
+function forwardsNothing(command: string, rest: readonly string[]): boolean {
+  if (command === 'run' || command === 'watch') return false
+  if (!(CORE_VERBS as readonly string[]).includes(command)) return false
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--sql') i++
+    else if (rest[i] === '--') return true
+  }
+  return false
+}
+
 /**
  * A crash from a hand-broken lock entry is that entry's fault: runs validate
  * no entry, so it surfaced as a raw TypeError (2026-10-14). The lock is
@@ -124,7 +172,9 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         // A name that is no verb here is the typo `vx rnu` is, not a request
         // for the whole reference: it printed 145 lines and no hint.
         const resolved = await (await plugins()).resolvePluginCommand(verb)
-        const unknown = resolved === null || 'declaredVerbs' in resolved
+        // A workspace that failed to load cannot say the verb exists: the
+        // whole reference and exit 0 hid the broken file (`vx okk` says so).
+        const unknown = resolved === null || !('plugin' in resolved)
         if (unknown && verb.startsWith('-')) {
           return refuse(
             'help',
@@ -134,15 +184,20 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
           )
         }
         if (unknown) {
-          const declared = resolved === null ? [] : resolved.declaredVerbs
+          const declared =
+            resolved !== null && 'declaredVerbs' in resolved ? resolved.declaredVerbs : []
+          const loadNote =
+            resolved !== null && 'loadError' in resolved
+              ? ` (plugin verbs could not be looked up: .vx/workspace failed to load: ${resolved.loadError})`
+              : ''
           return refuse(
             'help',
             rest,
-            `unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)`,
+            `unknown command: ${verb}${didYouMeanVerb(verb, declared)}${loadNote} (see \`vx help\`)`,
             'VX_E_UNKNOWN_COMMAND',
           )
         }
-        if (resolved !== null && !('loadError' in resolved)) return dispatch(verb, ['--help'])
+        return dispatch(verb, ['--help'])
       }
       await printHelp(await (await plugins()).pluginCommandHelp(), core ? verb : undefined)
       return 0
@@ -215,7 +270,7 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         // that returned 256 (a count of failures, say) exited 0.
         if (!Number.isInteger(code) || code < 0 || code > 255) {
           throw new UserError(
-            `plugin '${resolved.plugin.name}': command '${command}' resolved ${JSON.stringify(code)} instead of an exit code (an integer 0–255)`,
+            `plugin '${resolved.plugin.name}': command '${command}' resolved ${typeof code === 'bigint' ? `${String(code)}n` : typeof code === 'number' || code === undefined ? String(code) : JSON.stringify(code)} instead of an exit code (an integer 0–255)`,
           )
         }
         return code

package/src/cli/info.ts

@@ -97,11 +97,11 @@ function infoReport(f: InfoFacts): ui.Block {
       'cache store',
       f.cacheStore === null
         ? 'none: the cache dir holds the entries'
-        : `${tildePath(f.cacheStore)} (${formatBytes(f.cacheStoreBytes ?? 0)}, shared by this repo's checkouts)`,
+        : `${tildePath(f.cacheStore)} (${formatBytes(f.cacheStoreBytes ?? 0)}, shared by this workspace's checkouts)`,
     ],
     ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
     ['cache entries', describeEntries(f)],
-    // Only the settings a variable or the workspace changed.
+    // Only the settings a variable, the workspace or a plugin changed.
     ...(Object.values(f.settings).some((s) => s.source !== 'default')
       ? ([['settings', describeSettings(f.settings)]] as [string, string][])
       : []),
@@ -141,14 +141,15 @@ function describeEntries(f: InfoFacts): string {
 
 /**
  * The settings not at their default, with where each came from:
- * `run.timeout 30m (VX_RUN_TIMEOUT), cache.policy local:rw (.vx/workspace)`.
+ * `run.timeout 30m (VX_RUN_TIMEOUT), cache.policy local:rw (.vx/workspace)`,
+ * `cache.scope pr-2 (plugin @org/ci)`.
  */
 function describeSettings(settings: InfoFacts['settings']): string {
   return Object.entries(settings)
     .filter(([, s]) => s.source !== 'default')
     .map(
       ([path, s]) =>
-        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'}${s.refused === undefined ? '' : `, refused: ${s.refused}`})`,
+        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : s.source === 'plugin' ? `plugin ${s.plugin}` : '.vx/workspace'}${s.refused === undefined ? '' : `, refused: ${s.refused}`})`,
     )
     .join(', ')
 }

package/src/cli/init.ts

@@ -6,7 +6,7 @@
 // `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, readFileSync } from 'node:fs'
+import { existsSync, lstatSync, readFileSync, statSync } from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { gitTop, workspaceFileWritten } from '../handoff.js'
@@ -132,11 +132,17 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     dirs.push(d)
     if (d === top || path.dirname(d) === d) break
   }
-  if (dirs.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
+  const pkgRoot = packageRoot(dirs, top !== null)
+  // Outside git `dirs` reach `/`: a stray turbo.json or nx.json above the
+  // project took init over, as a stray package.json did (2026-10-28).
+  const own = top !== null ? dirs : dirs.slice(0, dirs.indexOf(pkgRoot ?? cwd) + 1)
+  if (own.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
     return migrate(dirs, parsed)
   }
-  const pkgRoot = packageRoot(dirs, top !== null)
-  return starter(marked ?? pkgRoot ?? cwd, pkgRoot, top === null, parsed)
+  // Asked of git itself: a kept workspace file is `top` too, and the
+  // `git init` hint went missing where the next run would refuse.
+  const noGit = marked === undefined ? top === null : (await gitTop(cwd)) === null
+  return starter(marked ?? pkgRoot ?? cwd, pkgRoot, noGit, parsed)
 }
 
 /**
@@ -314,6 +320,20 @@ function ownerNamed(dir: string): boolean {
   }
 }
 
+/**
+ * Whether anything stands at `file`, a dangling symlink included: writing
+ * through one created its target outside the workspace.
+ */
+function occupied(file: string): boolean {
+  try {
+    lstatSync(file)
+    return true
+  } catch {
+    // quiet: nothing there (a parent that is a file is refused at the write)
+    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]!
@@ -329,13 +349,14 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
   ] as const
   if (!args.force) {
     for (const [rel] of files) {
-      if (await Bun.file(path.join(root, rel)).exists()) {
+      if (occupied(path.join(root, rel))) {
         sayNotice('error', 'vx init', `${rel} exists. --force overwrites it`)
         return 1
       }
     }
   }
   if (!args.dry) {
+    for (const [rel] of files) refuseSymlink(path.join(root, rel), root)
     await mkdir(path.join(root, 'plugins'), { recursive: true }).catch(
       (err: NodeJS.ErrnoException) => {
         if (err.code !== 'EEXIST' && err.code !== 'ENOTDIR') throw err
@@ -344,7 +365,7 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
         )
       },
     )
-    for (const [rel, text] of files) await Bun.write(path.join(root, rel), text)
+    for (const [rel, text] of files) await writeNoFollow(path.join(root, rel), text, root)
   }
   const factory = /^export function (\w+)/m.exec(template.plugin)![1]!
   const workspaceFile =
@@ -423,7 +444,7 @@ async function starter(
 ): Promise<number> {
   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 init: --${args.mode} answers a Turbo or Nx workspace's question, and there is no turbo.json or nx.json here`,
       'VX_E_USAGE',
     )
   }
@@ -450,11 +471,20 @@ async function starter(
     ],
     [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)
+    const existing = names.filter((n) => existsSync(path.join(root, n)))
+    // Kept, a directory read as the workspace's marker, and every verb after
+    // then found none and sent the user back here.
+    const dir = existing.find((n) => statSync(path.join(root, n)).isDirectory())
+    if (dir !== undefined) {
+      throw new UserError(
+        `vx init: ${dir} is a directory, where the ${name === config ? 'project config' : 'workspace file'} goes; move it and re-run`,
+      )
+    }
+    if (existing.length > 0 && !args.force) kept.push(existing[0]!)
     else {
       files.push({ path: name, contents })
-      if (existing !== undefined && existing !== name) replaced.push(existing)
+      // Every other name goes too: a second config beside the one written.
+      replaced.push(...existing.filter((n) => n !== name))
     }
   }
   // vx's own housekeeping, as a run's first cache open and `vx lock` write them.
@@ -465,7 +495,10 @@ async function starter(
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
   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}`
+  // Run in the cwd, a git init below the root it chose hides the workspace from every verb.
+  const gitInit =
+    root === process.cwd() ? 'git init' : `git init ${path.relative(process.cwd(), root)}`
+  const next = `${noGit ? `${gitInit}, ` : ''}${hasScripts(pkgRoot) ? `bunx @vzn/vx-migrate${args.mjs ? ' --mjs' : ''} to make package.json scripts tasks, or ${declare}` : declare}`
   if (args.json === true) {
     ui.data(
       'out',
@@ -473,7 +506,7 @@ async function starter(
     )
     return 0
   }
-  const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json: one project, the root']]
+  const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json']]
   // 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'])
@@ -486,17 +519,19 @@ async function starter(
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
-  for (const f of files) refuseSymlink(path.join(root, f.path))
+  for (const f of files) refuseSymlink(path.join(root, f.path), root)
   const ran = await install(pkgRoot, false, plugins)
   if (ran.length > 0) rows.push(['installed', ...ran])
   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`,
-      )
-    })
+    await writeNoFollow(path.join(root, f.path), f.contents, root).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.