@vzn/vx 0.0.650 → 0.0.652

package/src/cli/docs.ts

@@ -5,7 +5,8 @@
 // whole, best first.
 
 import { VERSION } from '../version.js'
-import { detectColors, paint, parseDecimalInt, ui } from '../util/index.js'
+import { parseDecimalInt } from '../util/index.js'
+import * as ui from '../ui/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 
 const SITE = 'https://vznjs.github.io/vx/'
@@ -238,7 +239,7 @@ export async function docsCmd(
   const hits = searchDocs(pages, parsed.terms, parsed.limit)
   const query = parsed.terms.join(' ')
   if (parsed.json) {
-    process.stdout.write(`${JSON.stringify({ query, hits })}\n`)
+    ui.data('out', `${JSON.stringify({ query, hits })}\n`)
     return 0
   }
   if (hits.length === 0) {
@@ -249,15 +250,13 @@ export async function docsCmd(
     )
     return 0
   }
-  const c = detectColors(process.stdout)
-  process.stdout.write(
-    hits
-      .map((h) =>
-        c.enabled
-          ? `${ui.render([ui.excerpt(`${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`}`, h.text)], c)}${paint('', h.url, c, { dim: true })}\n`
-          : `── ${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}\n\n${h.text}\n`,
-      )
-      .join('\n'),
+  // Each hit an excerpt of the page, its link under it: off colour the
+  // bare markdown, as a pipe copies it.
+  ui.print(
+    'out',
+    ...hits.map((h) =>
+      ui.excerpt(`${h.page}.md${h.heading === '' ? '' : ` § ${h.heading}`} · ${h.url}`, h.text),
+    ),
   )
   return 0
 }

package/src/cli/help.ts

@@ -1,22 +1,15 @@
-import {
-  CORE_VERBS,
-  detectColors,
-  errorDocument,
-  maskedLine,
-  nearest,
-  paint,
-  refusalNotice,
-  ui,
-  wantsJson,
-  type ColorSupport,
-} from '../util/index.js'
+import { CORE_VERBS, errorDocument, maskedLine, nearest, wantsJson } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { detectColors, paint, refusalNotice, type ColorSupport } from '../ui/index.js'
 
 export async function printHelp(
   pluginCommands: readonly string[] = [],
   verb?: string,
 ): Promise<void> {
   const text = verb === undefined ? helpText(pluginCommands) : verbHelpText(verb)
-  process.stdout.write(paintHelp(text, helpColors(process.stdout, detectColors), paint))
+  // The reference a script greps: painted on a terminal only, and strips
+  // back to `text` exactly, so it goes out as written.
+  ui.data('out', paintHelp(text, helpColors(process.stdout, detectColors), paint))
 }
 
 /**
@@ -31,9 +24,6 @@ export function helpColors(
   return { enabled: stream.isTTY === true && detect(stream as NodeJS.WriteStream).enabled }
 }
 
-const VERB = '#06b6d4' // cyan-500 — the orchestrator's accent
-const TERM = '#22d3ee' // cyan-400 — a flag, a selector, an example
-
 /**
  * The reference with ANSI accents, line by line and never reflowed, so the
  * painted text strips back to `text` exactly: section headings bold (their
@@ -48,13 +38,12 @@ export function paintHelp(text: string, colors: ColorSupport, paint: Paint): str
       if (line === '') return line
       if (i === 0) {
         const [name, ...rest] = line.split(' ')
-        return [paint(VERB, name!, colors, { bold: true }), ...rest].join(' ')
+        return [paint('info', name!, colors, true), ...rest].join(' ')
       }
       const heading = /^([A-Z][^:]*?)( \(for [^)]*\))?:$/.exec(line)
       if (heading !== null) {
-        const qualifier =
-          heading[2] === undefined ? '' : paint('', heading[2], colors, { dim: true })
-        return `${paint('', heading[1]!, colors, { bold: true })}${qualifier}${paint('', ':', colors, { bold: true })}`
+        const qualifier = heading[2] === undefined ? '' : paint('muted', heading[2], colors)
+        return `${paint('strong', heading[1]!, colors)}${qualifier}${paint('strong', ':', colors)}`
       }
       // `  term   description`: a term is a flag, a `vx` form, a selector.
       const row = /^(\s+)(\S(?:.*?\S)?)(\s{2,}\S.*)?$/.exec(line)
@@ -66,11 +55,11 @@ export function paintHelp(text: string, colors: ColorSupport, paint: Paint): str
         if (description === '' && !(CORE_VERBS as readonly string[]).includes(verb)) return line
         const head = `vx ${verb}`
         const tail = term!.slice(head.length)
-        return `${indent}${paint(VERB, head, colors, { bold: true })}${tail === '' ? '' : paint(TERM, tail, colors)}${description}`
+        return `${indent}${paint('info', head, colors, true)}${tail === '' ? '' : paint('term', tail, colors)}${description}`
       }
       if (description === '') return line
       if (/^(-|\(|[\w-]+#)/.test(term!))
-        return `${indent}${paint(TERM, term!, colors)}${description}`
+        return `${indent}${paint('term', term!, colors)}${description}`
       return line
     })
     .join('\n')
@@ -215,9 +204,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,',
@@ -475,7 +464,7 @@ export function refuse(
 ): number {
   const line = `vx ${verb}: ${message}`
   ui.print('err', refusalNotice(`vx ${verb}`, message))
-  if (wantsJson(args)) process.stdout.write(errorDocument(code, maskedLine(line)))
+  if (wantsJson(args)) ui.data('out', errorDocument(code, maskedLine(line)))
   return 1
 }
 

package/src/cli/index.ts

@@ -5,21 +5,20 @@ import { VERSION } from '../version.js'
 import { checkSettingsEnv } from '../settings.js'
 import { CORE_VERBS, flagHint, printHelp, refuse, refusedWord, seeHelp } from './help.js'
 import {
-  detectColors,
   errorDocument,
+  hasControl,
   hideEnvFromTasks,
-  sayNotice,
   isFsRefusal,
   isOutOfFds,
   isUserError,
   maskedLine,
   nearest,
-  refusalNotice,
   thrownMessage,
-  ui,
   UserError,
   wantsJson,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { sayNotice, refusalNotice } from '../ui/index.js'
 
 // Every verb is imported when invoked, `run` included, and so is the
 // plugin-verb lookup: each pulls in the orchestrator and the workspace
@@ -32,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
@@ -71,6 +71,28 @@ 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 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
@@ -163,9 +185,7 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         )
       }
       // Painted, and the same words piped: a script reads `vx <version>`.
-      process.stdout.write(
-        `${ui.inline([ui.cmd('vx'), ' ', ui.tone('info', VERSION)], detectColors(process.stdout))}\n`,
-      )
+      ui.print('out', ui.line(ui.cmd('vx'), ' ', ui.tone('info', VERSION)))
       return 0
     }
     case 'run':
@@ -238,8 +258,7 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
       ): number => {
         sayNotice(tone, 'vx', text.replace(/^vx: /, '').trimEnd())
         // `vx --format json` puts the flag where the verb goes.
-        if (wantsJson([command, ...rest]))
-          process.stdout.write(errorDocument(code, maskedLine(json)))
+        if (wantsJson([command, ...rest])) ui.data('out', errorDocument(code, maskedLine(json)))
         return 1
       }
       const loadNote =

package/src/cli/info.ts

@@ -9,7 +9,9 @@ import { type FlakyTask } from '../history/index.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
-import { detectColors, MIN_BUN, ui, type ColorSupport } from '../util/index.js'
+import { MIN_BUN } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { type ColorSupport } from '../ui/index.js'
 import { envName } from '../settings.js'
 
 interface InfoArgs {
@@ -55,15 +57,18 @@ export async function infoCmd(args: readonly string[]): Promise<number> {
     ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
     warn: warnToStderr,
   })
-  process.stdout.write(
-    parsed.format === 'json'
-      ? `${JSON.stringify(facts)}\n`
-      : `${renderInfo(facts, detectColors(process.stdout))}\n`,
-  )
+  if (parsed.format === 'json') ui.data('out', `${JSON.stringify(facts)}\n`)
+  else ui.print('out', infoReport(facts))
   return 0
 }
 
+/** `vx info` as text: the report's lines for `colors`. */
 export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false }): string {
+  return infoReport(f).lines(colors).join('\n')
+}
+
+/** The `vx info` report: one field a fact. */
+function infoReport(f: InfoFacts): ui.Block {
   const rows: [string, string][] = [
     [
       'vx',
@@ -92,7 +97,7 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
       '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)],
@@ -125,7 +130,7 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
       typeof f.lockError === 'string' ? `refused: ${f.lockError}` : f.lockfile ? 'yes' : 'no',
     ],
   ]
-  return ui.report('vx info', rows).lines(colors).join('\n')
+  return ui.report('vx info', rows)
 }
 
 /** `812 (1.2 GB)`, or why the index cannot be read and its fix. */
@@ -195,6 +200,9 @@ function trimCores(n: number): string {
 
 /** `2 — app#test (3 of 7 runs failed on unchanged inputs); api#e2e (1 of 4)`, or `none`. */
 function describeProjects(f: InfoFacts): string {
+  // The count is the lock's: with none read, 0 would say the workspace has no project.
+  if (f.lockError != null) return '— (the lock is refused)'
+  if (!f.lockfile) return '— (no lock: `vx lock`)'
   return `${f.projects} (${f.tasks} task${f.tasks === 1 ? '' : 's'})`
 }
 

package/src/cli/init.ts

@@ -23,17 +23,14 @@ import {
 } from './upgrade.js'
 import { VERSION } from '../version.js'
 import {
-  detectColors,
   DOT_VX_GITATTRIBUTES,
   DOT_VX_GITIGNORE,
-  paint,
   refuseSymlink,
-  sayNotice,
-  SUCCESS,
-  ui,
   UserError,
   writeNoFollow,
 } from '../util/index.js'
+import * as ui from '../ui/index.js'
+import { sayNotice } from '../ui/index.js'
 import {
   findWorkspaceRoot,
   PROJECT_CONFIG_FILENAMES,
@@ -279,8 +276,9 @@ async function install(
     let said = ''
     const decoder = new TextDecoder()
     for await (const chunk of proc.stderr) {
-      process.stderr.write(chunk)
-      said += decoder.decode(chunk, { stream: true })
+      const text = decoder.decode(chunk, { stream: true })
+      ui.data('err', text)
+      said += text
     }
     const code = await proc.exited
     if (code !== 0) {
@@ -351,13 +349,22 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
   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(
-    `${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`,
+  const names = files.flatMap(([rel], i) => [...(i > 0 ? [' and '] : []), ui.strong(rel)])
+  ui.print('out', ui.line(ui.tone('ok', args.dry ? 'would write' : 'wrote', true), ' ', ...names))
+  ui.print(
+    'out',
+    ui.line(
+      'Declare it in ',
+      ui.path(workspaceFile),
+      ': ',
+      ui.cmd(`import { ${factory} } from '../plugins/${seam}.ts'`),
+      ', then ',
+      ui.cmd(`plugins: [${factory}(…)]`),
+    ),
+  )
+  ui.print(
+    'out',
+    ui.line('Test it: ', ui.cmd(`bun test plugins/${seam}.test.ts`), ' (needs @vzn/vx installed)'),
   )
   return 0
 }
@@ -460,7 +467,8 @@ async function starter(
   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(
+    ui.data(
+      'out',
       `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
     )
     return 0