@vzn/vx 0.0.486 → 0.0.489

package/package.json

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

package/src/cli/help.ts

@@ -1,7 +1,72 @@
-import { nearest } from '../util/index.js'
+import type { ColorSupport, paint as Paint } from '../orchestrator/index.js'
+import { CORE_VERBS, nearest } from '../util/index.js'
 
-export function printHelp(pluginCommands: readonly string[] = [], verb?: string): void {
-  process.stdout.write(verb === undefined ? helpText(pluginCommands) : verbHelpText(verb))
+export async function printHelp(
+  pluginCommands: readonly string[] = [],
+  verb?: string,
+): Promise<void> {
+  const text = verb === undefined ? helpText(pluginCommands) : verbHelpText(verb)
+  // The orchestrator is already loaded by the plugin-verb lookup every
+  // caller awaits first, so this import costs `vx --version` nothing.
+  const { detectColors, paint } = await import('../orchestrator/index.js')
+  process.stdout.write(paintHelp(text, helpColors(process.stdout, detectColors), paint))
+}
+
+/**
+ * Help paints on a terminal only. `FORCE_COLOR=1` set for a run's log in
+ * CI does not paint it: a script that greps `vx help` (or reads the flag
+ * list from it) gets plain text whatever forces colour elsewhere.
+ */
+export function helpColors(
+  stream: { isTTY?: boolean },
+  detect: (s: NodeJS.WriteStream) => ColorSupport,
+): ColorSupport {
+  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
+ * `(for <verb>)` dim), `vx <verb>` bold cyan, and the term an option or
+ * example line opens with cyan. Prose and continuation lines stay plain.
+ */
+export function paintHelp(text: string, colors: ColorSupport, paint: typeof Paint): string {
+  if (!colors.enabled) return text
+  const lines = text.split('\n')
+  return lines
+    .map((line, i) => {
+      if (line === '') return line
+      if (i === 0) {
+        const [name, ...rest] = line.split(' ')
+        return [paint(VERB, name!, colors, { bold: 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 })}`
+      }
+      // `  term   description`: a term is a flag, a `vx` form, a selector.
+      const row = /^(\s+)(\S(?:.*?\S)?)(\s{2,}\S.*)?$/.exec(line)
+      if (row === null) return line
+      const [, indent, term, description = ''] = row
+      if (/^vx \S/.test(term!)) {
+        const verb = term!.split(' ')[1]!
+        // Prose that opens with `vx` (`vx core runs tasks…`) is not a form.
+        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}`
+      }
+      if (description === '') return line
+      if (/^(-|\(|[\w-]+#)/.test(term!))
+        return `${indent}${paint(TERM, term!, colors)}${description}`
+      return line
+    })
+    .join('\n')
 }
 
 /**
@@ -96,11 +161,11 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
     '',
     'Artifacts (for run):',
-    '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
-    '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
-    '      --report[=markdown]  Print a markdown run report to stdout after the run.',
-    '      --report-file <path> Append that report to <path> (for $GITHUB_STEP_SUMMARY).',
-    '      --tag <k=v>          Label this invocation (repeatable); recorded on its history row.',
+    '      --summarize[=<path>]  Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
+    '      --profile[=<path>]    Write Chrome-trace JSON (default profile.json).',
+    '      --report[=markdown]   Print a markdown run report to stdout after the run.',
+    '      --report-file <path>  Append that report to <path> (for $GITHUB_STEP_SUMMARY).',
+    '      --tag <k=v>           Label this invocation (repeatable); recorded on its history row.',
     '',
     'Extensions (plugins):',
     '  vx core runs tasks in-process and nothing else. A dashboard, remote',

package/src/cli/index.ts

@@ -23,7 +23,7 @@ export async function run(argv: readonly string[]): Promise<number> {
   // which is the one place `--help` is not being asked of vx. Core verbs
   // only — a plugin verb owns its own arguments, `--help` included.
   if (command !== undefined && wantsHelp(command, rest)) {
-    printHelp(await (await plugins()).pluginCommandHelp(), command)
+    await printHelp(await (await plugins()).pluginCommandHelp(), command)
     return 0
   }
 
@@ -39,12 +39,12 @@ export async function run(argv: readonly string[]): Promise<number> {
         process.stderr.write(`vx: ${err.message}; \`vx help\` lists the verbs\n`)
         return 1
       }
-      printHelp(await (await plugins()).pluginCommandHelp())
+      await printHelp(await (await plugins()).pluginCommandHelp())
       return 0
     }
     case '--help':
     case '-h':
-      printHelp(await (await plugins()).pluginCommandHelp())
+      await printHelp(await (await plugins()).pluginCommandHelp())
       return 0
     case 'help': {
       // `vx help run` is the same question as `vx run --help`. A plugin verb
@@ -76,7 +76,7 @@ export async function run(argv: readonly string[]): Promise<number> {
           return 1
         }
       }
-      printHelp(await (await plugins()).pluginCommandHelp(), core ? verb : undefined)
+      await printHelp(await (await plugins()).pluginCommandHelp(), core ? verb : undefined)
       return 0
     }
     case '--version':

package/src/exec/env.ts

@@ -74,6 +74,11 @@ export function buildIsolatedEnv(opts: BuildEnvOptions): NodeJS.ProcessEnv {
   for (const [name, value] of Object.entries(opts.define)) {
     out[name] = value
   }
+  // A task's output is a pipe, so a tool asks no TTY and prints plain. vx
+  // forces colour, as Nx and Turbo do, and strips it where its own output
+  // is plain (`plainOutput`), so the cache holds one form for every
+  // machine. Any FORCE_COLOR the task already sees, or a NO_COLOR, wins.
+  if (out['FORCE_COLOR'] === undefined && !out['NO_COLOR']) out['FORCE_COLOR'] = '1'
 
   // A directory holding the delimiter cannot be named in PATH: split, it
   // became two entries naming nothing, the second RELATIVE, so resolved

package/src/orchestrator/index.ts

@@ -25,6 +25,7 @@ export { forwardedSignal } from './signals.js'
 // `vx cache prune` waits for a run on the workspace before it evicts.
 export { acquireRunLock } from './run-lock.js'
 export { defaultLogger, resolveOutputView } from './logger.js'
+export { detectColors, paint, type ColorSupport } from './colors.js'
 export type { Logger, OutputView } from './logger.js'
 export type { RunPlan, PlannedTask, PlanPrediction, CacheStatus } from './plan.js'
 export { formatDuration } from './summary.js'

package/src/orchestrator/plain-output.ts

@@ -0,0 +1,57 @@
+import type { TaskNode } from '../graph/index.js'
+import type { Logger } from './logger.js'
+
+// A prefix that may yet complete as a CSI or OSC sequence. An escape cut
+// at a chunk's end is held for the next chunk: stripped alone, its
+// remainder (`1m`) reached the log as text.
+// eslint-disable-next-line no-control-regex -- ESC is the point
+const PARTIAL_ESCAPE = /^\x1b(?:\[[0-?]*[ -/]*|\][^\x07\x1b]*\x1b?)?$/
+
+/**
+ * `sink` with terminal escapes stripped from task output. Tasks run with
+ * `FORCE_COLOR` (exec/env.ts), so their bytes carry colour wherever vx's
+ * own output is plain: a pipe, CI, `NO_COLOR`.
+ */
+export function plainOutput(sink: Logger): Logger {
+  const held = new Map<string, string>()
+  const strip = (key: string, chunk: string): string => {
+    const prior = held.get(key)
+    const text = prior === undefined ? chunk : prior + chunk
+    if (prior !== undefined) held.delete(key)
+    const esc = text.lastIndexOf('\x1b')
+    if (esc === -1) return text
+    if (PARTIAL_ESCAPE.test(text.slice(esc))) {
+      held.set(key, text.slice(esc))
+      return Bun.stripANSI(text.slice(0, esc))
+    }
+    return Bun.stripANSI(text)
+  }
+  const flush = (node: TaskNode, key: string, write: (n: TaskNode, c: string) => void): void => {
+    const rest = held.get(key)
+    if (rest === undefined) return
+    held.delete(key)
+    const text = Bun.stripANSI(rest)
+    if (text !== '') write(node, text)
+  }
+  // Delegated one by one, never spread: an embedder's logger may be a class
+  // whose methods live on its prototype and read `this`.
+  return {
+    status: (line) => sink.status(line),
+    ...(sink.runStart && { runStart: (info) => sink.runStart!(info) }),
+    ...(sink.taskStart && { taskStart: (node) => sink.taskStart!(node) }),
+    ...(sink.runEnd && { runEnd: () => sink.runEnd!() }),
+    taskStdout(node, chunk) {
+      const text = strip(`${node.id}\0out`, chunk)
+      if (text !== '' || chunk === '') sink.taskStdout(node, text)
+    },
+    taskStderr(node, chunk) {
+      const text = strip(`${node.id}\0err`, chunk)
+      if (text !== '' || chunk === '') sink.taskStderr(node, text)
+    },
+    taskComplete(node, outcome) {
+      flush(node, `${node.id}\0out`, (n, c) => sink.taskStdout(n, c))
+      flush(node, `${node.id}\0err`, (n, c) => sink.taskStderr(n, c))
+      sink.taskComplete(node, outcome)
+    },
+  }
+}

package/src/orchestrator/run.ts

@@ -59,6 +59,7 @@ import { assembleRunSummary, isPassStatus } from './telemetry.js'
 import type { RunContextRecord } from './telemetry.js'
 import { defaultLogger, resolveOutputView, type Logger } from './logger.js'
 import { detectColors, type ColorSupport } from './colors.js'
+import { plainOutput } from './plain-output.js'
 import { formatPersistentList } from './framed-output.js'
 import { LocalHistoryProvider } from './history.js'
 import { plan, type RunPlan } from './plan.js'
@@ -307,7 +308,12 @@ export async function run(options: RunOptions): Promise<RunSummary> {
   // outlives the run, and a renderer left behind reported the next run on
   // it twice (item 635). Otherwise a fresh internal bus.
   const bus = options.bus ?? createEventBus()
-  const unsubscribeTerminal = bus.subscribe(terminalSubscriber(sink))
+  // Tasks run with colour forced (exec/env.ts); where the terminal prints
+  // plain, their escapes are stripped. A custom logger gets the task's
+  // bytes as written, as the cache holds them: it formats its own output.
+  const unsubscribeTerminal = bus.subscribe(
+    terminalSubscriber(terminal === null || colors.enabled ? sink : plainOutput(sink)),
+  )
   const detach = (): void => {
     unsubscribeTerminal()
     terminal?.settle()

package/src/workspace/project-loader.ts

@@ -733,6 +733,7 @@ const BUN_MEMBERS_VX_READS: readonly PropertyKey[] = [
   'spawnSync',
   'stdout',
   'stringWidth',
+  'stripANSI',
   'version',
   'which',
   'write',